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Preface 


The OpenVMS Calling Standard defines the requirements, mechanisms, and 
conventions used in the OpenVMS interface that supports procedure-to-procedure 
calls for both Alpha and VAX environments. The standard defines the run-time 
data structures, constants, algorithms, conventions, methods, and functional 
interfaces that enable a native user-mode procedure to operate correctly in a 
multilanguage environment on Alpha and VAX systems. Properties of the run- 
time environment that must apply at various points during program execution 
are also defined. 


The 32-bit user mode of the OpenVMS Alpha standard provides a high degree of 
compatibility with current programs written for the OpenVMS VAX environment. 


The 64-bit user mode of the OpenVMS Alpha standard is a compatible superset of 
the OpenVMS Alpha 32-bit environment. 


The interfaces, methods, and conventions specified in this manual are primarily 
intended for use by implementers of compilers, debuggers, and other run-time 
tools, run-time libraries, and base operating systems. These specifications may or 
may not be appropriate for use by higher level system software and applications. 


This standard is under engineering change order (ECO) control. This manual 
includes all ECOs through ECO #44. ECOs are approved by Digital’s Calling 
Standard committee. 


Intended Audience 


This manual primarily defines requirements for compiler and debugger writers, 
but the information can apply to procedure calling for all programmers in various 
levels of programming. 


Document Structure 


This manual contains six chapters. Some chapters are restricted to either an 
Alpha or a VAX environment. 


Chapter 1 provides an overview of the standard, defines goals, and defines terms 
used in the text. 


Chapter 2 describes the primary conventions in calling a procedure in an | 
OpenVMS VAX environment. It defines the VAX register usage and argument- 
passing list as well as vector and scalar processor synchronization. 


Chapter 3 describes the fundamental concepts and conventions in calling a 
procedure in an OpenVMS Alpha environment. The chapter identifies the Alpha 
register usage and addressing, and focuses on aspects of the calling standard that 
pertain to procedure-to-procedure flow of control. 


Chapter 4 defines the argument-passing data types used in calling a procedure 
for both OpenVMS Alpha and OpenVMS VAX environments. 


Chapter 5 defines the argument descriptors used in calling a procedure for both 
OpenVMS Alpha and OpenVMS VAX environments. 


Chapter 6 describes the OpenVMS condition- and exception-handling 
requirements for both OpenVMS Alpha and OpenVMS VAX environments. 


Related Documents 
The following manuals contain related information: 
¢ VAX Architecture Reference Manual 
¢ Alpha Architecture Reference Manual 
¢ OpenVMS Programming Interfaces: Calling a System Routine 
¢ Guide to DECthreads 
¢ VAX/VMS Internals and Data Structures 
¢ OpenVMS AXP Internals and Data Structures 


For additional information on OpenVMS products and services, access the Digital 
OpenVMS World Wide Web site. Use the following URL: 


http: //www.openvms.digital.com 


Reader’s Comments 
Digital welcomes your comments on this manual. 


Print or edit the online form SYS$HELP:OPENVMSDOC_COMMENTS.TXT and 
send us your comments by: 


Internet openvmsdoc@zko.mts.dec.com 
Fax 603 881-0120, Attention: OpenVMS Documentation, ZK03-4/U08 
Mail OpenVMS Documentation Group, ZKO3-4/U08 


110 Spit Brook Rd. 
Nashua, NH 03062-2698 


How To Order Additional Documentation 


Use the following table to order additional documentation or information. 
If you need help deciding which documentation best meets your needs, call 
800-DIGITAL (800-344-4825). 


Telephone and Direct Mail 


Location Call 

U.S.A. DECdirect 
800-DIGITAL 
800-344-4825 

Puerto Rico 809-781-0505 


Canada 800-267-6215 Fax: 613-592-1946 

International = ~~ 

Internal Orders DTN: 264—4446 Fax: 603-884-3960 
603-884—4446 , 


Conventions 


Orders 


Fax 
Fax: 800-234-2298 


Fax: 809-749-8300 


Write 


Digital Equipment Corporation 
P.O. Box CS2008 
Nashua, NH 03061 


Digital Equipment Caribbean, Inc. 
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P.O. Box 11038 

Metro Office Park 

San Juan, Puerto Rico 00910—2138 


Digital Equipment of Canada, Ltd. 
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approved distributor 


US. Software Supply Business 
Digital Equipment Corporation 
10 Cotton Road 

Nashua, NH 03063-1260 
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The name of the OpenVMS AXP operating system has been changed to OpenVMS 
Alpha. Any references to OpenVMS AXP or AXP are synonymous with OpenVMS 


Alpha or Alpha. 


The following conventions are used to identify information specific to OpenVMS 
Alpha or to OpenVMS VAX: 


| Alpha 
<> 


The Alpha icon denotes the beginning of information 
specific to OpenVMS Alpha. 


The VAX icon denotes the beginning of information 


specific to OpenVMS VAX. 


The diamond symbol denotes the end of a section of 
information specific to OpenVMS Alpha or to OpenVMS 


VAX. 


The following conventions are also used in this manual: 


Ctrl/x 


A sequence such as Ctrl/x indicates that you must hold down 


the key labeled Ctrl while you press another key or a pointing 
device button. 


PF1 x or 
GOLD x 


A sequence such as PF1 x or GOLD x indicates that you must 
first press and release the key labeled PF1 or GOLD and then 


press and release another key or a pointing device button. 


GOLD key sequences can also have a slash (/), dash (—), or 
underscore (_) as a delimiter in EVE commands. 


xi 


() 


[] 


{} 


boldface text 


italic text 


UPPERCASE TEXT 


Monospace type 


numbers 


xii 


In examples, a key name enclosed in a box indicates that 
you press a key on the keyboard. (In text, a key name is not 
enclosed in a box.) 


Horizontal ellipsis points in examples indicate one of the 
following possibilities: 


e Additional optional arguments in a statement have been 
omitted. 


¢ The preceding item or items can be repeated one or more 
times. 


e Additional parameters, values, or other information can be 
entered. 


Vertical ellipsis points indicate the omission of items from 
a code example or command format; the items are omitted 
because they are not important to the topic being discussed. 


In command format descriptions, parentheses indicate that, if 
you choose more than one option, you must enclose the choices 
in parentheses. 


In command format descriptions, brackets indicate optional 
elements. You can choose one, none, or all of the options. 
(Brackets are not optional, however, in the syntax of a directory 
name in an OpenVMS file specification or in the syntax of a 
substring specification in an assignment statement.) 


In command format descriptions, braces indicate a required 
choice of options; you must choose one of the options listed. 


Boldface text represents the introduction of a new term or the 
name of an argument, an attribute, or a reason. 


Boldface text is also used to show user input in Bookreader 
versions of the manual. 


Italic text indicates important information, complete titles 

of manuals, or variables. Variables include information that 
varies in system output (Internal error number), in command 
lines (PRODUCER=name), and in command parameters in 
text (where device-name contains up to five alphanumeric 
characters). 


Uppercase text indicates a command, the name of a routine,, 
the name of a file, or the abbreviation for a system privilege. 


Monospace type indicates code examples and interactive screen 
displays. 


In the C programming language, monospace type in text 
identifies the following elements: keywords, the names 

of independently compiled external functions and files, 
syntax summaries, and references to variables or identifiers 
introduced in an example. 


A hyphen at the end of a command format description, 
command line, or code line indicates that the command or 
statement continues on the following line. 


All numbers in text are assumed to be decimal unless 
otherwise noted. Nondecimal radixes—binary, octal, or 
hexadecimal—are explicitly indicated. 
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Introduction 


This standard defines properties such as the run-time data structures, constants, 
algorithms, conventions, methods, and functional interfaces that enable a 
native user-mode procedure to operate correctly in a multilanguage and 
multithreaded environment on OpenVMS Alpha and OpenVMS VAX systems. 
These properties include the contents of key registers, format and contents of 
certain data structures, and actions that procedures must perform under certain 
circumstances. 


This standard also defines properties of the run-time environment that must 
apply at various points during program execution. These properties vary in scope 
and applicability. Some properties apply at all points throughout the execution 
of standard-conforming user-mode code and must, therefore, be held constant at 
all times. Examples of such properties include those defined for the stack pointer 
and various properties of the call-chain navigation mechanism. Other properties 
apply only at certain points, such as call conventions that apply only at the point 
of transfer of control to another procedure. 


Furthermore, some properties are optional depending on circumstances. For 
example, compilers are not obligated to follow the argument list conventions 
when a procedure and all of its callers are in the same module, have been 
analyzed by an interprocedural analyzer, or have private interfaces (such as 
language-support routines). 


Note 


In many cases, significant performance gains can be realized by selective 
use of nonstandard calls when the safety of such calls is known. Compiler 
or tools writers are encouraged to make full use of such optimizations. 


The OpenVMS Alpha portion of this calling standard is intended to provide a 
calling standard that contains a high degree of compatibility with the OpenVMS 
VAX environment. Conventions that differ are, for the most part, those that are 
dictated by differences between the Alpha and VAX hardware architectures. 


The procedure call mechanism depends on agreement between the calling and 
called procedures to interpret the argument list. The argument list does not fully 
describe itself. This standard requires language extensions to permit a calling 
program to generate some of the argument-passing mechanisms expected by 
called procedures. 


This standard specifies the following attributes of the interfaces between modules: 
¢ Calling sequence—instructions at the call site, entry point, and returns 


e Argument list—structure of the list describing the arguments to the called 
procedure 
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e Function value return—form and conventions for the return of the function 
value as a value or as a condition value to indicate success or failure 


e Register usage—which registers are preserved and who is responsible for 
preserving them 


e Stack usage—rules governing the use of the stack 
¢ Argument data types—data types of arguments that can be passed 


e Argument descriptor formats—how descriptors are passed for the more 
complex arguments 


¢ Condition handling—how exception conditions are signaled and how they are 
handled in a modular fashion 


e Stack unwinding—how the current thread of execution is aborted efficiently 


1.1 Applicability 


This standard defines the rules and conventions that govern the native user- 
mode run-time environment on Alpha and VAX processors. It is applicable to 
all products of Digital Equipment Corporation that execute in native user mode. 


Uses of this standard include: 


e All externally callable interfaces in Digital-supported, standard system 
software 


e All intermodule calls to major software components 


e All external procedure calls generated by OpenVMS language processors 
without interprocedural analysis or permanent private conventions (such as 
those used for language-support run-time library (RTL) routines) 


1.2 Architectural Level 


1.3 Goals 


This standard defines an implementation-level run-time software 
architecture for OpenVMS operating systems. 


The interfaces, methods, and conventions specified in this document are primarily 
intended for use by implementers of compilers, debuggers, and other run-time 
tools, run-time libraries, and base operating systems. These specifications may or 
may not be appropriate for use by higher-level system software and applications. 


Compilers and run-time libraries may provide additional support of these 
capabilities via interfaces that are more suited for compiler and application use. 
This specification neither prohibits nor requires such additional interfaces. 


Generally, this calling standard promotes the highest degree of performance, 
portability, efficiency, and consistency in the interface between called procedures 
of a common OpenVMS environment. Specifically, the calling standard: 


e Is applicable to all intermodule callable interfaces in the native software 
system. Specifically, the standard considers the requirements of important 
compiled languages including Ada, BASIC, Bliss, C, C++, COBOL, FORTRAN, 
Pascal, LISP, PL/I, and calls to the operating system and library procedures. 
The needs of other languages that the OpenVMS operating system may 
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support in the future must be met by the standard or by compatible revisions 
to it. 


Excludes capabilities for lower-level components (such as assembler routines) 
that cannot be invoked from the high-level languages. 


Allows the calling program and called procedure to be written in different 
languages. The standard reduces the need for using language extensions in 
mixed-language programs. 

Contributes to the writing of error-free, modular, and maintainable software, 
and promotes effective sharing and reuse of software modules. 


Provides the programmer with control over fixing, reporting, and flow of 
control when various types of exception conditions occur. 


Provides subsystem and application writers with the ability to override 
system messages toward a more suitable application-oriented interface. 


Adds no space or time overhead to procedure calls and returns that do not 
establish exception handlers, and minimizes time overhead for establishing 
handlers at the cost of increased time overhead when exceptions occur. 


The OpenVMS Alpha portion of this standard: 


Supports a 32-bit user-mode environment that provides a high degree of 
compatibility with the OpenVMS VAX environment. 


Supports a 64-bit user-mode environment that is a compatible superset of the 
OpenVMS Alpha 32-bit environment. 


Simplifies coexistence with VAX procedures that execute under the translated 
image environment. 


Simplifies the compilation of VAX assembler source to native Alpha object 
code. 


Supports a multilanguage, multithreaded execution environment, including 
efficient, effective support for the implementation of the multithread 
architecture (DECthreads). 


Provides an efficient mechanism for calling lightweight procedures that do 
not need or cannot expend the overhead of setting up a stack call frame. 


Provides for the use of a common calling sequence to invoke lightweight 
procedures that maintain only a register call frame and heavyweight 
procedures that maintain a stack call frame. This calling sequence allows a 
compiler to determine whether to use a stack frame based on the complexity 
of the procedure being compiled. A recompilation of a called routine that | 
causes a change in stack frame usage does not require a recompilation of its 
callers. 


Provides condition handling, traceback, and debugging for lightweight 
procedures that do not have a stack frame. 


Makes efficient use of the Alpha architecture, including effectively using a 
larger number of registers than is contained in a conventional VAX processor. 


Minimizes the cost of procedure calls. ¢ 
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The OpenVMS procedure calling mechanisms of this standard do not provide: 


e Checking of argument data types, data structures, and parameter access. The 
VAX and Alpha protection and memory management systems do not depend 
on correct interactions between user-level calling and called procedures. Such 
extended checking might be desirable in some circumstances, but system 
integrity does not depend on it. | 


¢ Information for an interpretive OpenVMS Debugger. The definition of the 
debugger includes a debug symbol table (DST) that contains the required 
descriptive information. 


1.4 Definitions 
The following terms are used in this standard: 


e Address: On VAX systems, a 32-bit value used to denote a position in 
memory. On Alpha systems, a 64-bit value used to denote a position in 
memory. However, many Alpha applications and user-mode facilities operate 
in such a manner that addresses are restricted only to values that are 
representable in 32 bits. This allows Alpha addresses often to be stored and 
manipulated as 32-bit longword values. In such cases, the 32-bit address 
value is always implicitly or explicitly sign-extended to form a 64-bit address 
for use by the Alpha hardware. 


e Argument list: A vector of entries (longwords on VAX processors, quadwords 
on Alpha processors) that represents a procedure parameter list and possibly 
a function value. 


e Asynchronous software interrupt: An asynchronous interruption of 
normal code flow caused by some software event. This interruption shares 
many of the properties of hardware exceptions, including forcing some 
out-of-line code to execute. 


¢ Bound procedure: A type of procedure that requires knowledge (at run 
time) of a dynamically determined larger enclosing scope to function correctly. 


¢ Call frame: The body of information that a procedure must save to allow 
it to properly return to its caller. A call frame may exist on the stack or in 
registers. A call frame may optionally contain additional information required 
by the called procedure. 


¢ Condition handler: A procedure designed to handle conditions (exceptions) 
when they occur during the execution of a thread. 


¢ Condition value: A 32-bit value (sign extended to a 64-bit value on Alpha 
processors) used to uniquely identify an exception condition. A condition 
value can be returned to a calling program as a function value or signaled 
using the OpenVMS signaling mechanism. 


¢ Descriptor: A mechanism for passing parameters where the address of 
a descriptor is an entry in the argument list. The descriptor contains the 
address of the parameter, data type, size, and additional information needed 
to describe fully the data passed. 


e Exception condition (or condition): An exceptional condition in the 
current hardware or software state that should be noted or fixed. Its 
existence causes an interrupt in program flow and forces execution of out-of- 
line code. Such an event might be caused by an exceptional hardware state, 
such as arithmetic overflows, memory access control violations, and so on, or 


1-4 


Introduction 
1.4 Definitions 


by actions performed by software, such as subscript range checking, assertion 
checking, or asynchronous notification of one thread by another. 


During the time the normal control flow is interrupted by an exception, that 
condition is termed active. 


Function: A procedure that returns a single value in accordance with the 
standard conventions for value returning. Additional values are returned by 
means of the argument list. 


Hardware exception: A category of exceptions that reflect an exceptional 
condition in the current hardware state that should be noted or fixed by the 
software. Hardware exceptions can occur synchronously or asynchronously 

with respect to the normal program flow. 


Immediate value: A mechanism for passing input parameters where the 
actual value is provided in the argument list entry by the calling program. 


Language-support procedure: A procedure called implicitly to implement 
high-level language constructs. Such procedures are not intended to be 
explicitly called from user programs. 


Library procedure: A procedure explicitly called using the equivalent of a 
call statement or function reference. Such procedures are usually language 
independent. 


Natural alignment: An attribute of certain data types that refers to the 
placement of the data so that the lowest addressed byte of the data has an 
address that is a multiple of the size of the data in bytes. Natural alignment 
of an aggregate data type generally refers to an alignment in which all 
members of the aggregate are naturally aligned. 


This standard defines five natural alignments: 

—- Byte—Any byte address 

— Word—Any byte address that is a multiple of 2 

— Longword—Any byte address that is a multiple of 4 

— Quadword—Any byte address that is a multiple of 8 
— Octaword—Any byte address that is a multiple of 16 


Procedure: A closed sequence of instructions that is entered from and 
returns control to the calling program. 


Procedure value: An address value that represents a procedure. In the 
VAX environment, a procedure value is the address of the entry mask that is 
interpreted by the CALL« instruction invoking the procedure. In an Alpha 
environment, a procedure value is the address of the procedure descriptor for 
the procedure. 


Process: An address space and at least one thread of execution. Selected 
security and quota checks are done on a per-process basis. 


This standard anticipates the possibility of the execution of multiple threads 
within a process. An operating system that provides only a single thread of 
execution per process is considered a special case of a multithreaded system 
where the maximum number of threads per process is one. 


Reference: A mechanism for passing parameters where the address of the 
parameter is provided in the argument list by the calling program. 
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Signal: A POSIX-defined concept used to cause out-of-line execution of code. 
(This term should not be confused with the OpenVMS usage of the word that 
more closely equates to exception as used in this document.) 


Standard call: Any transfer of control to a procedure by any means that 
presents the called procedure with the environment defined by this document 
and does not place additional restrictions, not defined by this document, on 
the called procedure. 


Standard-conforming procedure: A procedure that adheres to all the 
relevant rules set forth in this document. 


Thread of execution (or thread): An entity scheduled for execution on a 
processor. In language terms, a thread is a computational entity utilized by a 
program unit. Such a program unit might be a task, procedure, loop, or some 
other unit of computation. 


All threads executing within the same process share the same address space 
and other process contexts but have a unique per-thread hardware context 
that includes program counter, processor status, stack pointer, and other 
machine registers. 


This standard applies only to threads that execute within the context of a 
user-mode process and are scheduled on one or more processors according to 
software priority. All subsequent uses of the term thread in this standard 
refer only to such user-mode process threads. 


Thread-safe code: Code that is compiled in such a way as to ensure it will 
execute properly when run in a threaded environment. Thread-safe code 
usually adds extra instructions to do certain run-time checks and requires 
that thread local storage be accessed in a particular fashion. 


Undefined: Referring to operations or behavior for which there is 

no directing algorithm used across all implementations that support 
this standard. Such operations may be well defined for a particular 
implementation, but they still remain undefined with reference to this 
standard. The actions of undefined operations may not be required by 
standard-conforming procedures. 


Unpredictable: Referring to the results of an operation that cannot be 
guaranteed across all implementations of this standard. These results may be 
well defined for a particular implementation, but they remain unpredictable 
with reference to this standard. All results that are not specified in this 
standard, but are caused by operations defined in this standard, are 
considered unpredictable. A standard-conforming procedure cannot depend on 
unpredictable results. 
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This chapter describes the primary conventions in calling a procedure in an 
OpenVMS VAX environment. 
2.1 Register Usage 


In the VAX architecture, there are fifteen 32-bit wide, general-purpose hardware 
registers for use with scalar and vector program operations. This section defines 
the rules of scalar and vector register usage. 

2.1.1 Scalar Register Usage 


This standard defines several en ee VAX registers and their scalar use, 
as listed in Table 2-1. 


Table 2-1 VAX Register Usage 


Register Use 

PC Program counter. 

SP Stack pointer. 

FP Current stack frame pointer. This register must always point at the current 


frame. No modification is permitted within a procedure body. 


AP Argument pointer. When a call occurs, AP must point to a valid argument 
list. A procedure without parameters points to an argument list consisting 
of a single longword containing the value 0. 


Rl Environment value. When a procedure that needs an environment value 
is called, the calling program must set R1 to the environment value. See 
bound procedure value in Section 4.3. 


RO, R1 Function value return registers. These registers are not to be preserved 
by any called procedure. They are available as temporary registers to any 
called procedure. 


Registers R2 through R11 are to be preserved across procedure calls. The called 
procedure can use these registers, provided it saves and restores them using the 
procedure entry mask mechanism. The entry mask mechanism must be used so 
that any stack unwinding done by the condition-handling mechanism restores all 
registers correctly. In addition, PC, SP, FP, and AP are always preserved by the 
CALLS or CALLG instruction and restored by the RET instruction. However, a 
called procedure can use AP as a temporary register. 


If JSB routines are used, they must not save or modify any preserved registers 
(R2 through R11) not already saved by the entry mask mechanism of the calling 
program. 
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2.1.2 Vector Register Usage 
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This calling standard does not specify conventions for preserved vector registers, 
vector argument registers, or vector function value return registers. All such 
conventions are by agreement between the calling and called procedures. In 
the absence of such an agreement, all vector registers, including VO through 
V15, VLR, VCR, and VMR are scratch registers. Among cooperating procedures, 
a procedure that preserves or otherwise manipulates the vector registers by 
agreement with its callers must provide an exception handler to restore them 


during an unwind. 


2.2 Stack Usage 


Figure 2-1 shows the contents of the stack frame created for the called procedure 
by the CALLG or CALLS instruction. 


Figure 2-1 Stack Frame Generated by CALLG or CALLS Instruction 
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FP always points to the call frame (the condition-handler longword) of the calling 
procedure. Other uses of FP within a procedure are prohibited. Unless the 
procedure has a condition handler, the condition-handler longword contains all 
zeros. See Chapter 6 for more information on condition handlers. 


The contents of the stack located at addresses higher than the mask/PSW 
longword belong to the calling program; they should not be read or written by 
the called procedure, except as specified in the argument list. The contents of 
the stack located at addresses lower than SP belong to interrupt and exception 
routines; they are modified continually and unpredictably. 
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The called procedure allocates local storage by subtracting the required number 
of bytes from the SP provided on entry. This local storage is freed automatically 
by the return instruction (RET). 


Bit <28> of the mask/PSW longword is reserved to Digital for future extensions 
to the stack frame. 


2.3 Calling Sequence 


At the option of the calling procedure, the called procedure is invoked using the 
CALLG or CALLS instruction, as follows: 


CALLG arglst, proc 
CALLS argent, proc 


CALLS pushes the argument count argent onto the stack as a longword and sets 
the argument pointer, AP, to the top of the stack. The complete sequence using 
CALLS follows: 


push argn 


push argl 
CALLS #n, proc 


If the called procedure returns control to the calling procedure, control must 
return to the instruction immediately following the CALLG or CALLS instruction. 
Skip returns and GOTO returns are allowed only during stack unwind operations. 


The called procedure returns control to the calling procedure by executing the 
RET instruction. 


2.4 Argument List 


The argument list is the primary means of passing information to and receiving 
results from a procedure. 
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2.4.1 Format 
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Figure 2—2 shows the argument list format. 


Figure 2-2 Argument List Format 
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The first longword is always present and contains the argument count as an 
unsigned integer in the low byte. The 24 high-order bits are reserved to Digital 
and must be zero. To access the argument count, the called procedure must 
ignore the reserved bits and access the count as an unsigned byte (for example, 
MOVZBL, TSTB, or CMPB). 


The remaining longwords can be one of the following: 


e An uninterpreted 32-bit value (by immediate value mechanism). If the called 
' procedure expects fewer than 32 bits, it accesses the low-order bits and 
ignores the high-order bits. 


e An address (by reference mechanism). It is typically a pointer to a scalar data 
item, array, structure, record, or a procedure. 


e An address of a descriptor (by descriptor mechanism). See Chapter 5 for 
descriptor formats. 


The standard permits programs to call by immediate value, by reference, by 
descriptor, or by combinations of these mechanisms. Interpretation of each 
argument list entry depends on agreement between the calling and called 
procedures. High-level languages use the reference or descriptor mechanisms for 
passing input parameters. OpenVMS system services and VAX BLISS, VAX C, 
DEC C, DEC C++, or VAX MACRO programs use all three mechanisms. 


A procedure with no arguments is called with a list consisting of a 0 argument 
count longword, as follows: 


CALLS #0, proc 


A missing or null argument—for example, CALL SUB(A,,B)—is represented 

by an argument list entry consisting of a longword 0. Some procedures allow 
trailing null arguments to be omitted and others require all arguments. See each 
procedure’s specification for details. 


The argument list must be treated as read-only data by the called procedure and 
might be allocated in read-only memory at the option of the calling program. 
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2.4.2 Argument Lists and High-Level Languages 


Functional notations for procedure calls in high-level languages are mapped into 
VAX argument lists according to the following rules: 


e Arguments are mapped from left to right to increasing argument list offsets. 
The leftmost (first) argument has an address of arglst+4, the next has an 
address of arglst+8, and so on. The only exception to this is when arglst+4 
specifies where a function value is to be returned, in which case the first 
argument has an address of arglst+8, the second argument has an address of 
arglst+12, and so on. See Section 2.5 for more information. 


¢ Each argument position corresponds to a single VAX argument list entry. 
For the C and C++ languages, a floating-point argument or a record struct 
that is larger than 32 bits may be passed by value using more than one VAX 
argument list entry. In this case, the argument count in the argument list 
reflects the actual number of argument list entries rather than the number of 
C or C++ language arguments. 


2.4.2.1 Order of Argument Evaluation 
Because most high-level languages do not specify the order of evaluation of 
arguments (with respect to side effects), those language processors can evaluate 
arguments in any convenient order. 


In constructing an argument list on the stack, a language processor can evaluate 
arguments from right to left and push their values on the stack. If call-by- 
reference semantics are used, argument expressions can be evaluated from left 
to right, with pointers to the expression values or descriptors being pushed from 
right to left. 


Note 


The choice of argument evaluation order and code generation strategy is 
constrained only by the definition of the particular language. Do not write 
programs that depend on the order of evaluation of arguments. 


2.4.2.2 Language Extensions for Argument Transmission 
This calling standard permits arguments to be passed by immediate value, 


by reference, or by descriptor. By default, all language processors except VAX 
BLISS, VAX C, and VAX MACRO pass arguments by reference or by descriptor. 


Language extensions are needed to reconcile the different argument-passing 
mechanisms. In addition to the default passing mechanism used, each language 
processor is required to give you explicit control, in the calling program, of the 
argument-passing mechanism for the data types supported by the language. 


Table 2—2 lists various argument data-type groups. In the table, the value Yes 
means the language processor is responsible for providing the user with explicit 
control of that argument-passing mechanism group. 
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Table 2-2 Argument-Passing Mechanisms with User Explicit Control 


Data Type Group Section Value Reference Descriptor 
Atomic <= 32 bits 4.1 Yes Yes Yes 
Atomic > 32 bits 4.1 No Yes Yes 
String 4.2 No Yes Yes 
Miscellaneous 4.3 No! No No 
Array 5 No Yes Yes 


1For languages that support the bound procedure value data type, a language extension is required 
to pass it by immediate value in order to be able to interface with OpenVMS system services and other 
software. See Section 4.3. 


For example, DEC Fortran provides the following intrinsic compile-time functions: 


%VAL(arg) By immediate value mechanism. Corresponding argument list entry 
is the value of the argument arg as defined in the language. 

%?REF (arg) By reference mechanism. Corresponding argument list entry contains 
the address of the value of the argument arg as defined in the 
language. . 

%DESCR(arg) By descriptor mechanism. Corresponding argument list entry 


contains the address of a descriptor of the argument arg as defined 
in Chapter 5 and in the language. 


Use these intrinsic functions in the syntax of a procedure call to control 
generation of the argument list. For example: 


CALL SUB1($VAL(123), REF(X), %DESCR(A)) 
For more information, see the DEC Fortran language documentation. 


In other languages, you can achieve the same effect by making appropriate 
attributes of the declaration of SUB1 in the calling program. Thus, you might 
write the following after making the external declaration for SUB1: 


CALL SUB1 (123, X, A) 


2.5 Function Value Returns 
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A function value is returned in register RO if its data type can be represented in 
32 bits, or in registers RO and R1 if its data type can be represented in 64 bits, 
provided the data type is not a string data type (see Section 4.2). 


If the data type requires fewer than 32 bits, then R1 and the high-order bits of RO 
are undefined. If the data type requires 32 or more bits but fewer than 64 bits, 
then the high-order bits of R1 are undefined. Two separate 32-bit entities cannot 
be returned in RO and R1 because high-level languages cannot process them. 


In all other cases (the function value needs more than 64 bits, the data type is 
a string, the size of the value can vary from call to call, and so on), the actual 
argument list and the formal argument list are shifted one entry. The new 
first entry is reserved for the function value. In this case, one of the following 
mechanisms is used to return the function value: 


e Ifthe maximum length of the function value is known (for example, octaword 
integer, H_floating, or fixed-length string), the calling program can allocate 
the required storage and pass the address of the storage or a descriptor for 
the storage as the first argument. 
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¢ Ifthe maximum length of a string function value is not known to the calling 
program, the calling program can allocate a dynamic string descriptor. The 
called procedure then allocates storage for the function value and updates the 
contents of the dynamic string descriptor using OpenVMS Run-Time Library 
procedures. For information about dynamic strings, see Section 5.3. 


e Ifthe maximum length of a fixed-length string (see Section 5.2) or a varying 
string (see Section 5.8) function value is not known to the calling program, 
the calling program can indicate that it expects the string to be returned on 
top of the stack. For more information about the function value return, see 
Section 2.5.1. 


Some procedures, such as operating system calls and many library procedures, 
return a success or failure value as a longword function value in RO. Bit <0> of 
the value is set (Boolean true) for a success and clear (Boolean false) for a failure. 
The particular success or failure status is encoded in the remaining 31 bits, as 
described in Section 6.1. 


2.5.1 Returning a Function Value on Top of the Stack 


If the maximum length of the function value is not known, the calling program 
can optionally allocate certain descriptors with the POINTER field set to 0, 
indicating that no space has been allocated for the value. If the called procedure 
finds POINTER 0, it fills in the POINTER, LENGTH, and other extent fields to 
describe the actual size and placement of the function value. This function value 
is copied to the top of the stack as control returns to the calling program. 


This is an exception to the usual practice because the calling program regains 
control at the instruction following the CALLG or CALLS sequence with the 
contents of SP restored to a value different from the one it had at the beginning 
of its CALLG or CALLS calling sequence. 


This technique applies only to the first argument in the argument list. Also, the 
called procedure cannot assume that the calling program expects the function 
value to be returned on the stack. Instead, the called procedure must check the 
CLASS field. If the descriptor is one that can be used to return a value on the 
stack, the called procedure checks the POINTER field. If POINTER is not 0, 
the called procedure returns the value using the semantics of the descriptor. If 
POINTER is 0, the called procedure fills in the POINTER and LENGTH fields 
and returns the value to the top of the stack. 


Also, when POINTER is 0, the contents of RO and R1 are unspecified by the 
called procedure. Once the called procedure fills in the POINTER field and other 
extent fields, the calling program may pass the descriptor as an argument to 
other procedures. 
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2.5.1.1. Returning a Fixed-Length or Varying String Function Value 


If a called procedure can return its function value on the stack as a fixed-length 
(see Section 5.2) or varying string (see Section 5.8), the called procedure must 
also take the following actions (determined by the CLASS and POINTER fields of 
the first descriptor in the argument list): 


CLASS POINTER Called Procedure’s Action 


S=1 Not 0 Copy the function value to the fixed-length area specified by the 
descriptor and space fill (hex 20 if ASCII) or truncate on the 
- right. The entire area is always written according to Section 5.2. 


S=1 0 Return the function value on top of the stack after filling in 
. POINTER with the first address of the string and LENGTH with 
the length of the string to complete the descriptor according to 


Section 5.2. 

VS=11 Not 0 Copy the function value to the varying area specified by 
the descriptor and fill in CURLEN and BODY according to 
Section 5.8. 

VS=11 0 Return the function value on top of the stack after filling in 


POINTER with the address of CURLEN and MAXSTRLEN 
with the length of the string in bytes (same value as contents of 
CURLEN) according to Section 5.8. 


Other - Error. A condition is signaled. 


In both the fixed-length and varying string cases, the string is unaligned. 
Specifically, the function value is allocated on top of the stack with no unused 
bytes between the stack pointer value contained at the beginning of the CALLS 
or CALLG sequence and the last byte of the string. 


2.6 Vector and Scalar Processor Synchronization 
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There are two kinds of synchronization between a scalar and vector processor 
pair: memory synchronization and exception synchronization. 


Memory synchronization with the caller of a procedure that uses the vector 
processor is required because scalar machine writes (to main memory) might 
still be pending at the time of entry to the called procedure. The various forms 
of write-cache strategies allowed by the VAX architecture combined with the 
possibly independent scalar and vector memory access paths implies that a 
scalar store followed by a CALL«x followed by a vector load is. not safe without an 
intervening MSYNC. : 


Within a procedure that uses the vector processor, proper memory and exception 
synchronization might require use of an MSYNC instruction, a SYNC instruction, 
or both, prior to calling or upon being called by another procedure. Further, for 
calls to other procedures, the requirements can vary from call to call, depending 
on details of actual vector usage. 


An MSYNC instruction (without a SYNC) at procedure entry, at procedure 

exit, and prior to a call provides proper synchronization in most cases. A 

SYNC instruction without an MSYNC prior to a CALLx (or RET) is sometimes 
appropriate. The remaining two cases, where both or neither MSYNC and SYNC 
are needed, are rare. 


Refer to the VAX vector architecture section in the VAX MACRO and Instruction 
Set Reference Manual for the specific rules on what exceptions are ensured to be 
reported by MSYNC and other MFVP instructions. 


$e 
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2.6.1 Memory Synchronization 


Every procedure is responsible for synchronization of memory operations with 
the calling procedure and with procedures it calls. If a procedure executes vector 
loads or stores, one of the following must occur: 


e An MSYNC instruction (a form of the MFVP instruction) must be executed 
before the first vector load and store to synchronize with memory operations 
issued by the caller. While an MSYNC instruction might typically occur in 
the entry code sequence of a procedure, exact placement might also depend on 
a variety of optimization considerations. 


e An MSYNC instruction must be executed after the last vector load or store 
to synchronize with memory operations issued after return. While an 
MSYNC instruction might typically occur in the return code sequence of a 
procedure, exact placement might also depend on a variety of optimization 
considerations. 


e An MSYNC instruction must be executed between each vector load and store 
and each standard call to other procedures to synchronize with memory 
operations issued by those procedures. 


Any procedure that executes vector loads or stores is responsible for synchronizing 
with potentially conflicting memory operations in any other procedure. However, 
execution of an MSYNC instruction to ensure scalar and vector memory 
synchronization can be omitted when it can be determined for the current 
procedure that all possibly incomplete vector load and stores operate only on 
memory not accessed by other procedures. 


2.6.2 Exception Synchronization 


Every procedure must ensure that no exception can be raised after the current 
frame is changed (as a result of a CALL« or RET). If a procedure executes any 
vector instruction that might raise an exception, then a SYNC instruction (a form 
of the MFVP instruction) must be executed prior to any subsequent CALL«x or 
RET. 


However, if the only exceptions that can occur are certain to be reported by an 
MSYNC instruction that is otherwise needed for memory synchronization, then 
the SYNC is redundant and can be omitted as an optimization. 


Moteover, if the only exceptions that can occur are certain to be reported by one 
jor more MFVP instructions that read the vector control registers, then the SYNC 
_isagdundant and can be omitted as an optimization. 
a aa 
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This chapter describes the fundamental concepts and conventions for calling 

a procedure in an Alpha environment. The following sections identify register 
usage and addressing, and focus on aspects of the calling standard that pertain to 
procedure-to-procedure flow control. 


3.1 Register Usage 


The 64-bit-wide, general-purpose Alpha hardware registers divide into two 
groups: 

e 6 Integer 

¢ Floating point 


The first 32 general-purpose registers support integer processing and the second 
32 support floating-point operations. 


3.1.1 Integer Registers 


This standard defines the usage of the Alpha general-purpose integer registers as 
listed in Table 3-1. 


Table 3-1 Alpha Integer Registers 
Register Usage 


RO Function value register. In a standard call that returns a nonfloating-point 
function result in a register, the result must be returned in this register. 
In a standard call, this register may be modified by the called procedure 
without being saved and restored. This register is not to be preserved by 
any called procedure. 


Rl Conventional scratch register. In a standard call, this register may be 
modified by the called procedure without being saved and restored. This 
register is not to be preserved by any called procedure. 


R2-15 Conventional saved registers. Ifa standard-conforming procedure modifies 
one of these registers, it must save and restore it. 


R16-21 Argument registers. In a standard call, up to six nonfloating-point items of 
the argument list are passed in these registers. In a standard call, these 
registers may be modified by the called procedure without being saved and 
restored. 


R22-24 Conventional scratch registers. In a standard call, these registers may be 
modified by the called procedure without being saved and restored. 


(continued on next page) 
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3.1 Register Usage 


Table 3-1 (Cont.) Alpha Integer Registers 


Register 


R25 


R26 


R27 


R28 


R29 


R30 


R31 


Usage 


Argument information (AD register. In a standard call, this register 
describes the argument list. (See Section 3.7.1 for a detailed description.) 
In a standard call, this register may be modified by the called procedure 
without being saved and restored. 


Return address (RA) register. In a standard call, the return address must 
be passed in this register. In a standard call, this register may be modified 
by the called procedure without being saved and restored. 


Procedure value (PV) register. In a standard call, the procedure value of 
the procedure being called is passed in this register. In a standard call, this 
register may be modified by the called procedure without being saved and 
restored. 


Volatile scratch register. The contents of this register are always 
unpredictable after any external transfer of control either to or from a 
procedure. This applies to both standard and nonstandard calls. This 
register may be used by the operating system for external call fixup, 
autoloading, and exit sequences. 


Frame pointer (FP). The contents of this register define, among other things, 
which procedure is considered current. Details of usage and alignment are 
defined in Section 3.6. 


Stack pointer (SP). This register contains a pointer to the top of the current 
operating stack. Aspects of its usage and alignment are defined by the 
hardware architecture. Various software aspects of its usage and alignment 
are defined in Section 3.7.1. 


ReadAsZero/Sink (RZ). Hardware defines binary zero as a source operand 
and sink (no effect) as a result operand. 


3.1.2 Floating-Point Registers 


This standard defines the usage of the Alpha general-purpose floating-point 
registers as listed in Table 3-2. 


Table 3-2 Alpha Floating-Point Registers 


Register 


FO 


Fl 


F2-9 
F10-15 


F16-21 
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Usage 


Floating-point function value register. In a standard call that returns a 
floating-point result in a register, this register is used to return the real part 
of the result. In a standard call, this register may be modified by the called 
procedure without being saved and restored. 


Floating-point function value register. In a standard call that returns a 
complex floating-point result in registers, this register is used to return 
the imaginary part of the result. In a standard call, this register may be 
modified by the called procedure without being saved and restored. 


Conventional saved registers. If a standard-conforming procedure modifies 
one of these registers, it must save and restore it. 


Conventional scratch registers. In a standard call, these registers may be 
modified by the called procedure without being saved and restored. 


Argument registers. In a standard call, up to six floating-point arguments 
may be passed by value in these registers. In a standard call, these registers 
may be modified by the called procedure without being saved and restored. 


(continued on next page) 
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Table 3-2 (Cont.) Alpha Floating-Point Registers 


Register Usage 


F22-30 Conventional scratch registers. In a standard call, these registers may be 
modified by the called procedure without being saved and restored. 


F31 ReadAsZero/Sink. Hardware defines binary zero as a source operand and. 
sink (no effect) as a result operand. 


3.2 Address Representation 


An address is a 64-bit value used to denote a position in memory. However, 

for compatibility with OpenVMS VAX, many Alpha applications and user-mode 
facilities operate in such a manner that addresses are restricted only to values 
that are representable in 32 bits. This allows Alpha addresses often to be stored 
and manipulated as 32-bit longword values. In such cases, the 32-bit address 
value is always implicitly or explicitly sign extended to form a 64-bit address for 
use by the Alpha hardware. 


3.3 Procedure Representation 


One distinguishing characteristic of any calling standard is how procedures 

are represented. The term used to denote the value that uniquely identifies a 
procedure is a procedure value. If the value identifies a bound procedure, it is 
called a bound procedure value. 


In the Alpha portion of this calling standard, all procedure values are defined to 
be the address of the data structure (a procedure descriptor) that describes that 
procedure. So, any procedure can be invoked by calling the address stored at 
offset 8 from the address represented by the procedure value. 


Note that a simple (unbound) procedure value is defined as the address of 

that procedure’s descriptor (see Section 3.4). This provides slightly different 
conventions than would be used if the address of the procedure’s code were used 
as it is in many calling standards. 


A bound procedure value is defined as the address of a bound procedure descriptor 
that provides the necessary information for the bound procedure to be called (see 
Section 3.7.4). 


3.4 Procedure Types 
This standard defines the following basic types of procedures: 
¢ Stack frame procedure—Maintains its caller’s context on the stack 
¢ Register frame procedure—Maintains its caller’s context in registers 


¢ Null frame procedure—Does not establish a context and, therefore, 
executes in the context of its caller 


A compiler can choose which type of procedure to generate based on the 
requirements of the procedure in question. A calling procedure does not need to 
know what type of procedure it is calling. 


Every procedure must have an associated structure that describes which type 

of procedure it is and other procedure characteristics. This structure, called a 
procedure descriptor, is a quadword-aligned data structure that provides basic 
information about a procedure. This data structure is used to interpret the call 
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chain at any point in a thread’s execution. It is typically built at compile time 
and usually is not accessed at run time except to support exception processing or 
other rarely executed code. 


Read access to procedure descriptors is done through a procedure interface 
described in Section 3.6.2. This allows for future compatible extensions to these © 
structures. 


The purpose of defining a procedure descriptor for a procedure and making that 
procedure descriptor accessible to the run-time system is twofold: 


¢ To make invocations of that procedure visible to and interpretable by facilities 
such as the debugger, exception-handling system, and the unwinder. 


* To ensure that the context of the caller saved by the called procedure 
can be restored if an unwind occurs. (For a description of unwinding, see 
Section 6.7.) 


3.4.1 Stack Frame Procedures 
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The stack frame of a procedure consists of a fixed part (the size of which is known 
at compile time) and an optional variable part. Certain optimizations can be 
done if the optional variable part is not present. Compilers must also recognize 
unusual situations such as the following that can effectively cause a variable part 
of the stack to exist: 


¢ A called routine may use the stack as a means to return certain types of 
function values (see Section 3.8.7 for more information). 


¢ A called routine that allocates stack space may take an exception in 
its routine prologue before it becomes current. This situation must be 
considered since the stack expansion happens in the context of the caller (see 
Section 3.7.5 for more information). 


For this reason, a fixed-stack usage version of this procedure type cannot 
make standard calls. 


The variable-stack usage version of this type of procedure is referred to as full 
function and can make standard calls to other procedures. 
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3.4.2 Procedure Descriptor for Procedures with a Stack Frame 


A stack frame procedure descriptor (PDSC) built by a compiler provides 
information about a procedure with a stack frame. The minimum size of the 
descriptor is 32 bytes defined by constant PDSC$K_MIN_STACK_SIZE. An 

‘optional PDSC extension in 8-byte increments supports exception-handling 
requirements. 


The fields defined in the stack frame descriptor are illustrated in Figure 3-1 and 
described in Table 3-3. 


Figure 3-1 Stack Frame Procedure Descriptor (PDSC) 


PDSC | | quadword aligned 


RSA_OFFSET FLAGS ; 
FRET ; 


ENTRY ; 


re 
emasen ee 
| 
rae 


PDSC$K_MIN_STACK_SIZE = 32 
End of required part of procedure descriptor 








~ STACK _HANDLER 32 
:40 
STACK _HANDLER_DATA 
PDSC$K_MAX_STACK SIZE = 48 
FRET = PDSC$V_FUNC_RETURN 
EM = PDSC$V_EXCEPTION_MODE 
ZK-4649A-GE 
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Table 3-3 Contents of Stack Frame Procedure Descriptor (PDSC) 


Field Name Contents 
PDSC$W_FLAGS The PDSC descriptor flag bits <15:0> are defined as follows: 

PDSC$V_KIND A 4-bit field <3:0> that identifies the type of procedure 
descriptor. For a procedure with a stack frame, this 
field must specify a value 9 (defined by constant 
PDSC$K_KIND_FP_STACK). 

PDSC$V_ If set to 1, this descriptor has an extension for 

HANDLER_VALID the stack handler (PDSC$Q_STACK_HANDLER) 
information. 

PDSC$V_ If set to 1, the handler can be reinvoked, allowing an 

HANDLER_ occurrence of another exception while the handler is 

REINVOKABLE already active. If this bit is set to 0, the exception 
handler cannot be reinvoked. Note that this bit must 
be 0 when PDSC$V_HANDLER_VALID is 0. 

PDSC$V_ If set to 1, the HANDLER_VALID bit must be 1, 

HANDLER_DATA_ the PDSC extension STACK_HANDLER_DATA field 

VALID contains valid data for the exception handler, and 


PDSC$V_BASE_ 
REG_IS_FP 


PDSC$V_REI_ 
RETURN 


Bit 9 


PDSC$V_BASE_ 
FRAME 


3-6 


the address of PDSC$Q_STACK_HANDLER_DATA 
will be passed to the exception handler as defined in 
Section 6.2. 


If this bit is set to 0, the SP is the base register to 
which PDSC$L_SIZE is added during an unwind. A 
fixed amount of storage is allocated in the procedure 
entry sequence, and SP is modified by this procedure 
only in the entry and exit code sequence. In this case, 
FP typically contains the address of the procedure 
descriptor for the procedure. A procedure for which 
this bit is 0 cannot make standard calls. 


If this bit is set to 1, FP is the base address and the 
procedure has a minimum amount of stack storage 
specified by PDSC$L_SIZE. A variable amount of 
stack storage can be allocated by modifying SP in the 
entry and exit code of this procedure. 


If set to 1, the procedure expects the stack at entry 
to be set, so an REI instruction correctly returns 
from the procedure. Also, if set, the contents of the 
RSA$Q_SAVED_RETURN field in the register save 
area are unpredictable and the return address is 
found on the stack (see Figure 3-4). 


| Must be 0 (reserved). 


For compiled code, this bit must be set to 0. If set 
to 1, indicates the logical base frame of a stack that 
precedes all frames corresponding to user code. The 
interpretation and use of this frame and whether 
there are any predecessor frames is system software 
defined (and subject to change). 


(continued on next page) 
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Table 3-3 (Cont.) Contents of Stack Frame Procedure Descriptor (PDSC) 


Field Name 


PDSC$W_RSA_OFFSET 


PDSC$V_FUNC_ 
RETURN 


PDSC$V_EXCEPTION_ 
MODE 


Contents 


PDSC$V_TARGET_ If set to 1, the exception handler for this procedure is 

INVO invoked when this procedure is the target invocation 
of an unwind. Note that a procedure is the target 
invocation of an unwind if it is the procedure in 
which execution resumes following completion of the 
unwind. For more information, see Chapter 6. 


If set to 0, the exception handler for this procedure is 
not invoked. Note that when PDSC$V_HANDLER_ 
VALID is 0, this bit must be 0. 


PDSC$V_NATIVE For compiled code, this bit must be set to 1. 


PDSC$V_NO_ For compiled code, this bit must be set to 1. 
JACKET 

PDSC$V_TIE_ For compiled code, this bit must be 0. Reserved for 
FRAME use by system software. 

Bit 15 Must be 0 (reserved). 


Signed offset in bytes between the stack frame base (SP or FP as indicated by 
PDSC$V_BASE_REG_IS_FP) and the register save area. This field must be a 
multiple of 8, so that PDSC$W_RSA_OFFSET added to the contents of SP or 
FP (PDSC$V_BASE_REG_IS_FP) yields a quadword-aligned address. 


A 4-bit field <11:8> that describes which registers are used for the function 
value return (if there is one) and what format is used for those registers. 


Table 3—7 lists and describes the possible encoded values of PDSC$V_FUNC_ 
RETURN. 


A 3-bit field <14:12> that encodes the caller’s desired exception-reporting 
behavior when calling certain mathematically oriented library routines. The 
possible values for this field are defined as follows: 


Value Name Meaning 

0 PDSC$K_ Raise exceptions for all error conditions 
EXCEPTION_MODE_ __ except for underflows producing a zero 
SIGNAL result. This is the default mode. 

1 PDSC$K_ . Raise exceptions for all error conditions 
EXCEPTION_MODE_ (including underflow). 
SIGNAL_ALL 

2 PDSC$K_ Raise no exceptions. Create only finite 
EXCEPTION_MODE_ _. values (no infinities, denormals, or NaNs). 
SIGNAL_SILENT In this mode, either the function result or 


the C language errno variable must be 
examined for any error indication. 


3 PDSC$K_ Raise no exceptions except as controlled 
EXCEPTION_MODE___by separate IEEE exception enable bits. 
FULL_IEEE Create infinities, denormals, or NaN 

values according to the IEEE floating-point 
standard. 

4 PDSC$K_ Perform the exception-mode behavior 
EXCEPTION_MODE_ _ specified by this procedure’s caller. 
CALLER 


(continued on next page) 
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Table 3—3 (Cont.) Contents of Stack Frame Procedure Descriptor (PDSC) 


Field Name 


PDSC$W_SIGNATURE_ 
OFFSET 


PDSC$Q_ENTRY 


PDSC$L_SIZE 


PDSC$W_ENTRY_ 
LENGTH 


PDSC$L_IREG_MASK 


PDSC$L_FREG_MASK 


PDSC$Q_STACK_ 
HANDLER 


PDSC$Q_STACK_ 
HANDLER_DATA 


Contents 


A 16-bit signed byte offset from the start of the procedure descriptor. This 
offset designates the start of the procedure signature block (if any). A 0 
in this field indicates that no signature information is present. Note that 
in a bound procedure descriptor (as described in Section 3.7.4), signature 
information might be present in the related procedure descriptor. A 1 in 
this field indicates a standard default signature. An offset value of 1 is not 
otherwise a valid offset because both procedure descriptors and signature 
blocks must be quadword aligned. 


Absolute address of the first instruction of the entry code sequence for the 
procedure. 


Unsigned size, in.bytes, of the fixed portion of the stack frame for this 
procedure. The size must be a multiple of 16 bytes to maintain the minimum 
stack alignment required by the Alpha hardware architecture and stack 
alignment during a call (defined in Section 3.7.1). PDSC$L_SIZE cannot be 0 
for a stack-frame type procedure, since the stack frame must include space for 
the register save area. 


The value of SP at entry to this procedure can be calculated by adding 
PDSC$L_SIZE to the value SP or FP, as indicated by PDSC$V_BASE_REG_ 
IS_FP. a 


Unsigned offset, in bytes, from the entry point to the first instruction in the 
procedure code segment following the procedure prologue (that is, following 
the instruction that updates FP to establish this procedure as the current 
procedure). 


Bit vector (0-31) specifying the integer registers that are saved in the register 
save area on entry to the procedure. The least significant bit corresponds to 
register RO. Never set bits 31, 30, 28, 1, and 0 of this mask, since R31 is the 
integer read-as-zero register, R30 is the stack pointer, R28 is always assumed 
to be destroyed during a procedure call or return, and R1 and RO are never 
preserved registers. In this calling standard, bit 29 (corresponding to the FP) 
must always be set. 


Bit vector (0-31) specifying the floating-point registers saved in the register 
save area on entry to the procedure. The least significant bit corresponds 
to register FO. Never set bit 31 of this mask, since it corresponds to the 


floating-point read-as-zero register. 


Absolute address to the procedure descriptor for a run-time static exception- 
handling procedure. This part of the procedure descriptor is optional. It 
must be supplied if either PDSC$V_HANDLER_VALID is 1 or PDSC$V_ 
HANDLER_DATA_VALID is 1 (which requires that PDSC$V_HANDLER_ 
VALID be 1). 


If PDSC$V_HANDLER_VALID is 0, then the contents or existence of 
PDSC$Q_STACK_HANDLER is unpredictable. 


Data (quadword) for the exception handler. This is an optional quadword and 
needs to be supplied only if PDSC$V_HANDLER_DATA_ VALID is 1. 


If PDSC$V_HANDLER_DATA._ VALID is 0, then the contents or existence of 
PDSC$Q_ STACK_HANDLER_DATA is unpredictable. 


3.4.3 Stack Frame Format 


The stack of a stack frame procedure consists of a fixed part (the size of which is 
known at compile time) and an optional variable part. There are two basic types 
of stack frames: 


e Fixed size 


e Variable size 
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Even though the exact contents of a stack frame are determined by the compiler, 
all stack frames have common characteristics. 


Various combinations of PDSC$V_BASE_REG_IS_FP and PDSC$L_SIZE can be 
used as follows: 


¢ When PDSC$V_BASE_REG_IS_FP is 0 and PDSC$L_SIZE is 0, then the 
procedure utilizes no stack storage and SP contains the value of SP at entry 
to the procedure. (Such a procedure must be a register frame procedure.) 


¢ When PDSC$V_BASE_REG_IS_FP is 0 and PDSC$L_SIZE is a nonzero 
value, then the procedure has a fixed amount of stack storage specified by 
PDSC$L_SIZE, all of which is allocated in the procedure entry sequence, and 
SP is modified by this procedure only in the entry and exit code sequences. 
(Such a procedure may not make standard calls.) 


¢ When PDSC$V_BASE_REG_IS_FP is 1 and PDSC$L_SIZE is a nonzero 
value, then the procedure has a fixed amount of stack storage specified by 
PDSC$L_SIZE, and may have a variable amount of stack storage allocated by 
modifying SP in the body of the procedure. (Such a procedure must be a stack 
frame procedure.) 


¢ The combination when PDSC$V_BASE_REG_IS FP is 1 and PDSC$L_SIZE 
is 0 is illegal because it violates the rules for R29 (FP) usage that requires 
R29 to be saved (on the stack) and restored. 


3.4.3.1 Fixed-Size Stack Frame 
Figure 3—2 illustrates the format of the stack frame for a procedure with a 
fixed amount of stack that uses the SP register as the stack base pointer (when 
PDSC$V_BASE_REG_IS_FP is 0). In this case, R29 (FP) typically contains the 
address of the procedure descriptor for the current procedure (see Section 3.6.1). 


Some parts of the stack frame are optional and occur only as required by the 
particular procedure. As shown in the figure, the field names within brackets are 
optional fields. Use of the arguments passed in memory field appending the 
end of the descriptor is described in Sections 3.4.3.3 and 3.8.2. 


For information describing the fixed temporary locations and register save area, 
see Sections 3.4.3.3 and 3.4.3.4. 
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Figure 3-2 Fixed-Size Stack Frame Format 


octaword aligned 
:0 (from SP) 


[Fixed temporary locations] 


-RSA_OFFSET 
(from SP) 


Register save area 


[Fixed temporary locations] 


[Argument home area] 


‘SIZE (from SP) 


[Arguments passed in memory] 
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3.4.3.2 Variable-Size Stack Frame 
Figure 3-3 illustrates the format of the stack frame for procedures with a varying 
amount of stack when PDSC$V_BASE_REG_IS_FP is 1. In this case, R29 (FP) 
contains the address that points to the base of the stack frame on the stack. This 
frame-base quadword location contains the address of the current procedure’s 
descriptor. 
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Figure 3-3 Variable-Size Stack Frame Format 


octaword aligned 


:0 (from SP) 
[Stack temporary area] 
:0 (from FP) 
Procedure descriptor address 
:8 (from FP) 
[Fixed temporary locations] 

:RSA_OFFSET 

(from FP) 


Register save area 


[Fixed temporary locations] 


[Argument home area] 


‘SIZE (from FP) 


{Arguments passed in memory] 
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Some parts of the stack frame are optional and occur only as required by the 
particular procedure. In Figure 3-3, field names within brackets are optional 
fields. Use of the arguments passed in memory field appending the end of the 
descriptor is described in Sections 3.4.3.3 and 3.8.2. 


For more information describing the fixed temporary locations and register 
save area, see Sections 3.4.3.3 and 3.4.3.4. 


A compiler can use the stack temporary area pointed to by the SP base register 
for fixed local variables, such as constant-sized data items and program state, 

as well as for dynamically sized local variables. The stack temporary area may 
also be used for dynamically sized items with a limited lifetime, for example, a 
dynamically sized function result or string concatenation that cannot be stored 
directly in a target variable. When a procedure uses this area, the compiler 


3-11 


OpenVMS Alpha Conventions 
3.4 Procedure Types 


must keep track of its base and reset SP to the base to reclaim storage used by 
temporaries. 


3.4.3.3 Fixed Temporary Locations for All Stack Frames 


The fixed temporary locations are optional sections of any stack frame that 
contain language-specific locations required by the procedure context of some 
high-level languages. This may include, for example, register spill area, language- 
specific exception-handling context (such as language-dynamic exception-handling 
information), fixed temporaries, and so on. 


The argument home area (if allocated by the compiler) can be found with the 
PDSC$L_SIZE offset in the last fixed temporary locations at the end of the stack 
frame. It is adjacent to the arguments passed in memory area to expedite 
the use of arguments passed (without copying). The argument home area is a 
region of memory used by the called procedure for the purpose of assembling in 
contiguous memory the arguments passed in registers, adjacent to the arguments 
passed in memory, so all arguments can be addressed as a contiguous array. This 
area can also be used to store arguments passed in registers if an address for 
such an argument must be generated. Generally, 6 + 8 bytes of stack storage is 
allocated by the called procedure for this purpose. 


If a procedure needs to reference its arguments as a longword array or construct 
a structure that looks like an in-memory longword argument list, then it might 
allocate enough longwords in this area to hold all of the argument list and, 
optionally, an argument count. In that case, argument items passed in memory 
must be copied to this longword array. 


The high-address end of the stack frame is defined by the value stored in 
PDSC$L_SIZE plus the contents of SP or FP, as indicated by PDSC$V_BASE_ 
REG_IS_FP. The high-address end is used to determine the value of SP for the 
predecessor procedure in the calling chain. 


3.4.3.4 Register Save Area for All Stack Frames 
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The register save area is a set of consecutive quadwords in which registers 
saved and restored by the current procedure are stored (see Figure 3-4). The 
register save area begins at the location pointed to by the offset PDSC$W_RSA_ 
OFFSET from the frame base register (SP or FP as indicated by PDSC$V_BASE_ 
REG_IS_FP), which must yield a quadword-aligned address. The set of registers 
saved in this area contain the return address followed by the registers specified in 
the procedure descriptor by PDSC$L_IREG_MASK and PDSC$L_FREG_MASK. 


All registers saved in the register save area (other than the saved return address) 
must have the corresponding bit set in the appropriate procedure descriptor 
register save mask even if the register is not a member of the set of registers 
required to be saved across a standard call. Failure to do so will prevent the 
correct calculation of offsets within the save area. 


Figure 3-4 illustrates the fields in the register save area (field names within 
brackets are optional fields). Quadword RSA$Q_ SAVED_RETURN is the first 


field in the save area and it contains the contents of the return address register. 


The optional fields vary in size (8-byte increments) to preserve, as required, 
the contents of the integer and floating-point hardware registers used in the 
procedure. 
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Figure 3-4 Register Save Area (RSA) Layout 





RSA quadword aligned 
SAVED_RETURN oe a L_ 
(R26 in a standard call) = T) 
8 
[Preserved integer registers] 
[Preserved floating point registers] 
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The algorithm for packing saved registers in the quadword-aligned register save 
area is: 


1. The return address is saved at the lowest address of the register save area 
(offset 0). 


2. All saved integer registers (as indicated by the corresponding bit in PDSC$L_ 
IREG_MASK being set to 1) are stored, in register-number order, in 
consecutive quadwords, beginning at offset 8 of the register save area. 


3. All saved floating-point registers (as indicated by the corresponding bit in 
PDSC$L_FREG_MASK being set to 1) are stored, in register-number order, in 
consecutive quadwords following the saved integer registers. 


Note 


Floating-point registers saved in the register save area are stored as 

a 64-bit exact image of the register (for example, no reordering of bits 
is done on the way to or from memory). Compilers must use an STT 

instruction to store the register regardless of floating-point type. 


The preserved register set must always include R29 (FP), since it will always be 
used. 


If the return address register is not to be preserved (as is the case for a 
standard call), then it must be stored at offset 0 in the register save area and 
the corresponding bit in the register save mask must not be set. 


However, if a nonstandard call is made that requires the return address register 
to be saved and restored, then it must be stored in both the location at offset 0 in 
the register save area and at the appropriate location within the variable part of 
the save area. In addition, the appropriate bit of PDSC$L_IREG_MASK must be 
set to 1. 


The example register save area shown in Figure 3-5 illustrates the register 
packing when registers R10, R11, R15, FP, F2, and F3 are being saved for a 
procedure called with a standard call. 


3-13 


OpenVMS Alpha Conventions 
3.4 Procedure Types 


Figure 3-5 Register Save Area (RSA) Example 


RSA | quadword aligned 
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3.4.4 Register Frame Procedure 
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A register frame procedure does not maintain a call frame on the stack and 
must, therefore, save its caller’s context in registers. This type of procedure is 
sometimes referred to as a lightweight procedure, referring to the expedient 
way of saving the call context. 


Such a procedure cannot save and restore nonscratch registers. Because a 
procedure without a stack frame must use scratch registers to maintain the 
caller’s context, such a procedure cannot make a standard call to any other 
procedure. 


A procedure with a register frame can have an exception handler and can handle 
exceptions in the normal way. Such a procedure can also allocate local stack 
storage in the normal way, although it might not necessarily do so. 
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Note 


Lightweight procedures have more freedom than might be apparent. By 
using appropriate agreements with callers of the lightweight procedure, 
with procedures that the lightweight procedure calls, and by the use of 
unwind handlers, a lightweight procedure can modify nonscratch registers 
and can call other procedures. 


Such agreements may be by convention (as in the case of language- 
support routines in the RTL) or by interprocedural analysis. However, | 
calls employing such agreements are not standard calls and might not be 
fully supported by a debugger; for example, the debugger might not be 
able to find the contents of the preserved registers. 


Since such agreements must be permanent (for upwards compatibility of 
object code), lightweight procedures should in general follow the normal 
restrictions. 


3.4.5 Procedure Descriptor for Procedures with a Register Frame 


A register frame procedure descriptor built by a compiler provides 
information about a procedure with a register frame. The minimum size of 
the descriptor is 24 bytes (defined by PDSC$K_MIN_REGISTER_SIZE). An 
optional PDSC extension in 8-byte increments supports exception-handling 
requirements. 


The fields defined in the register frame procedure descriptor are illustrated in 
Figure 3-6 and described in Table 3-4. 
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Figure 3-6 Register Frame Procedure Descriptor (PDSC) 


PDSC quadword aligned 


SAVE_RA SAVE_FP FLAGS 
SIGNATURE_OFFSET | EM FRET Reserved 
<14:12>| <11:8> 


: ENTRY 


SIZE 16 


PDSC$K_MIN_REGISTER_SIZE = 24 
End of required part of procedure descriptor 











:20 


REG_HANDLER 


REG_HANDLER_DATA 





PDSC$K_MAX_REGISTER_SIZE = 40 
FRET = PDSC$V_FUNC_RETURN - 
EM = PDSC$V_EXCEPTION_MODE 
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Table 3-4 Contents of Register Frame Procedure Descriptor (PDSC) 


Field Name 


PDSC$W_FLAGS 


Contents 


The PDSC descriptor flag bits <15:0> are defined as follows: 


PDSC$V_KIND 


PDSC$V_ 
HANDLER_VALID 


PDSC$V_ 
HANDLER_ 
REINVOKABLE 


PDSC$V_ 
HANDLER_DATA_ 
VALID ~ 


PDSC$V_BASE_ 
REG_IS FP 


PDSC$V_REI_ 
RETURN 


Bit 9 


PDSC$V_BASE_ 
FRAME 


A 4-bit field <3:0> that identifies the type of procedure 
descriptor. For a procedure with a register frame, this 
field must specify a value 10 (defined by constant 
PDSC$K_KIND_FP_REGISTER). 


If set to 1, this descriptor has an extension for 
the stack handler (PDSC$Q_REG_HANDLER) 
information. 


If set to 1, the handler can be reinvoked, allowing 

an occurrence of another exception while the handler 
is already active. If this bit is set to 0, the exception 
handler cannot be reinvoked. This bit must be 0 when 
PDSC$V_HANDLER_VALID is 0. 


If set to 1, the HANDLER_VALID bit must be 1 and 
the PDSC extension STACK_HANDLER_ DATA field 
contains valid data for the exception handler, and 
the address of PDSC$Q_STACK_HANDLER_DATA 
will be passed to the exception handler as defined in 
Section 6.2. 


If this bit is set to 0, the SP is the base register to 
which PDSC$L_SIZE is added during an unwind. A 
fixed amount of storage is allocated in the procedure 
entry sequence, and SP is modified by this procedure 
only in the entry and exit code sequence. In this case, 
FP typically contains the address of the procedure 
descriptor for the procedure. Note that a procedure 
that sets this bit to 0 cannot make standard calls. 


If this bit is set to 1, FP is the base address and 

the procedure has a fixed amount of stack storage 
specified by PDSC$L_SIZE. A variable amount of 
stack storage can be allocated by modifying SP in the 
entry and exit code of this procedure. 


If set to 1, the procedure expects the stack at entry 
to be set, so an REI instruction correctly returns 
from the procedure. Also, if set, the contents of the 
PDSC$B_SAVE_RA field are unpredictable and the 
return address is found on the stack. 


Must be 0 (reserved). 


For compiled code, this bit must be 0. If set to 

1, indicates the logical base frame of a stack that 
precedes all frames corresponding to user code. The 
interpretation and use of this frame and whether 
there are any predecessor frames is system software 
defined (and subject to change). 


(continued on next page) 
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Table 3—4 (Cont.) Contents of Register Frame Procedure Descriptor (PDSC) 


Field Name Contents 


PDSC$V_TARGET_ If set to 1, the exception handler for this procedure is 

INVO invoked when this procedure is the target invocation 
of an unwind. Note that a procedure is the target 
invocation of an unwind if it is the procedure in 
which execution resumes following completion of the 
unwind. For more information, see Chapter 6. 


If set to 0, the exception handler for this procedure is 
not invoked. Note that when PDSC$V_HANDLER_ 
VALID is 0, this bit must be 0. 


PDSC$V_NATIVE For compiled code, this bit must be set to 1. 


PDSC$V_NO_ For compiled code, this bit must be set to 1. 
JACKET 
PDSC$V_TIE_ For compiled code, this bit must be 0. Reserved for 
FRAME use by system software. 
Bit 15 Must be 0 (reserved). 
PDSC$B_SAVE_FP Specifies the number of the register that contains the saved value of the frame 


pointer (FP) register. 
In a standard procedure, this field must specify a scratch register so as not to 
violate the rules for procedure entry code as specified in Section 3.7.5. 


PDSC$B_SAVE_RA Specifies the number of the register that contains the return address. If this 
, procedure uses standard call conventions and does not modify R26, then this 
field can specify R26. 


In a standard procedure, this field must specify a scratch register so as not to 
violate the rules for procedure entry code as specified in Section 3.7.5. 


PDSC$V_FUNC_ A 4-bit field <11:8> that describes which registers are used for the function 

RETURN value return (if there is one) and what format is used for those registers. 
Table 3-7 lists and describes the possible encoded values of PDSC$V_FUNC_ 
RETURN. 


(continued on next page) 
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Table 3—4 (Cont.) Contents of Register Frame Procedure Descriptor (PDSC) 


Field Name 


PDSC$V_EXCEPTION_ 


MODE 


PDSC$W_SIGNATURE_ 


OFFSET 


PDSC$Q_ENTRY 


PDSC$L_SIZE 


PDSC$W_ENTRY_ 
LENGTH 


PDSC$Q_REG_ 
HANDLER 


Contents 


A 3-bit field <14:12> that encodes the caller’s desired exception-reporting 
behavior when calling certain mathematically oriented library routines. The 
possible values for this field are defined as follows: 


Value Name 


0 


PDSC$K, 


EXCEPTION _MODE_ 


SIGNAL 
PDSC$K_ 


EXCEPTION_MODE_ 


SIGNAL_ALL 
PDSC$K_ 


EXCEPTION_MODE_ 


SIGNAL_SILENT 


PDSC$K_ 


EXCEPTION_MODE_ 


FULL_IEEE 


PDSC$K 


EXCEPTION _MODE_ 


CALLER 


Meaning 


Raise exceptions for all error conditions 
except for underflows producing a zero 
result. This is the default mode. 


Raise exceptions for all error conditions 
(including underflows). 


Raise no exceptions. Create only finite 
values (no infinities, denormals, or NaNs). 
In this mode, either the function result or 
the C language errno variable must be 
examined for any error indication. 


Raise no exceptions except as controlled 
by separate IEEE exception enable bits. 
Create infinities, denormals, or NaN 
values according to the IEEE floating-point 
standard. 


Perform the exception-mode behavior 
specified by this procedure’s caller. 


A 16-bit signed byte offset from the start of the procedure descriptor. This 
offset designates the start of the procedure signature block (if any). A zero 
(0) in this field indicates no signature information is present. Note that 
in a bound procedure descriptor (as described in Section 3.7.4), signature 
information might be present in the related procedure descriptor. A 1 in 
this field indicates a standard default signature. An offset value of 1 is not 
otherwise a valid offset because both procedure ly and signature 


blocks must be quadword aligned. 


Absolute address of the first instruction of the entry code sequence for the 
procedure. 


Unsigned size in bytes of the fixed portion of the stack frame for this 
procedure. The size must be a multiple of 16 bytes to maintain the minimum 
stack alignment required by the Alpha hardware architecture and stack 
alignment during a call (defined in Section 3.7.1). 


Unsigned offset in bytes from the entry point to the first instruction in the 
procedure code segment following the procedure prologue (that is, following 
the instruction that updates FP to establish this procedure as the current 

procedure). 


Absolute address to the procedure descriptor for a run-time static exception- 
handling procedure. This part of the procedure descriptor is optional. It 
must be supplied if either PDSC$V_HANDLER_VALID is 1 or PDSC$V_ 
HANDLER_DATA_VALID is 1 (which requires that PDSC$V_HANDLER_ 
VALID be 1). 


If PDSC$V_HANDLER_VALID is 0, then the contents or existence of 


PDSC$Q_REG_HANDLER is unpredictable. 


(continued on next page) 
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Table 3-4 (Cont.) Contents of Register Frame Procedure Descriptor (PDSC) 


Field Name Contents 
PDSC$Q_REG_ Data (quadword) for the exception handler. This is an optional quadword and 
HANDLER_DATA needs to be supplied only if PDSC$V_HANDLER_DATA_VALID is 1. 


If PDSC$V_HANDLER_DATA_VALID is 0, then the contents or existence of 
PDSC$Q_REG_HANDLER_DATA is unpredictable. 


3.4.6 Null Frame Procedures 


A procedure may conform to this standard even if it does not establish its own 
context if, in all circumstances, invocations of that procedure do not need to be 
visible or debuggable. This is termed executing in the context of the caller 
and is similar in concept to a conventional VAX JSB procedure. For the purposes 
of stack tracing or unwinding, such a procedure is never considered to be current. 


For example, if a procedure does not establish an exception handler or does not 
save and restore registers, and does not extend the stack, then that procedure 
might not need to establish a context. Likewise, if that procedure does extend the 
stack, it still might not need to establish a context if the immediate caller either 
cannot be the target of an unwind or is prepared to reset the stack if it is the 
target of an unwind. 


The circumstances under which procedures can run in the context of the caller 
are complex and are not fully specified by this standard. 


As with the other procedure types previously described, the choice of whether to 
establish a context belongs to the called procedure. By defining a null procedure 
descriptor format, the same invocation code sequence can be used by the caller for 
all procedure types. 


3.4.7 Procedure Descriptor for Null Frame Procedures 
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The null frame procedure descriptor built by a compiler provides information 
about a procedure with no frame. The size of the descriptor is 16 bytes (defined 
by PDSC$K_NULL_SIZE). 


The fields defined in the null frame descriptor are illustrated in Figure 3-7 and 
described in Table 3-5. 
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Figure 3-7 Null Frame Procedure Descriptor (PDSC) Format 


PDSC quadword aligned 
Must be zero FLAGS 


SIGNATURE_OFFSET MBZ *FRET Reserved 
<15:12> | <11:8> 


ENTRY 





PDSC$K_NULL_SIZE = 16 
*FRET = PDSC$V_FUNC_RETURN 


ZK-4655A-GE 
Table 3-5 Contents of Null Frame Procedure Descriptor (PDSC) 
Field Name Contents 
PDSC$W_FLAGS The PDSC descriptor flag bits <15:0> are defined as follows: 
| PDSC$V_KIND A 4-bit field <3:0> that identifies the type of procedure 
descriptor. For a null frame procedure, this field must 
specify a value 8 (defined by constant PDSC$K_ 
KIND_NULL). 
Bits 4-7 Must be 0. 
PDSC$V_REI_ Bit 8. If set to 1, the procedure expects the stack at 
RETURN entry to be set, so an REI instruction correctly returns 
from the procedure. Also, if set, the contents of the 
PDSC$B_SAVE_RA field are unpredictable and the 
return address is found on the stack. 
Bit 9 Must be 0 (reserved). 
PDSC$V_BASE_ For compiled code, this bit must be 0. If set to 
FRAME 1, indicates the logical base frame of a stack that 
precedes all frames corresponding to user code. The 
interpretation and use of this frame and whether 
there are any predecessor frames is system software 
defined (and subject to change). 
Bit 11 Must be 0 (reserved). 
PDSC$V_NATIVE For compiled code, this bit must be set to 1. 
PDSC$V_NO_ For compiled code, this bit must be set to 1. 
JACKET 
PDSC$V_TIE_ For compiled code, this bit must be 0. Reserved for 
FRAME use by system software. 
Bit 15 Must be 0 (reserved). 
PDSC$V_FUNC_ A 4-bit field <11:8> that describes which registers are used for the function 
RETURN value return (if there is one) and what format is used for those registers. 


Table 3-7 lists and describes the possible encoded values of PDSC$V_FUNC_ 
RETURN. 


(continued on next page) 
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Table 3—5 (Cont.) Contents of Null Frame Procedure Descriptor (PDSC) 


Field Name 


Contents 


PDSC$W_SIGNATURE_ A 16-bit signed byte offset from the start of the procedure descriptor. This 


OFFSET 


offset designates the start of the procedure signature block (if any). A zero 
in this field indicates that no signature information is present. Note that 
in a bound procedure descriptor (as described in Section 3.7.4), signature 
information might be present in the related procedure descriptor. A 1 in 
this field indicates a standard default signature. An offset value of 1 is not 
otherwise a valid offset because both procedure descriptors and signature 
blocks must be quadword aligned. 


PDSC$Q_ENTRY The absolute address of the first instruction of the entry code sequence for the 


procedure. 


3.5 Procedure Signatures 
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As a means of enhancing certain aspects of program interoperation between 
images built from native Alpha code and images translated from VAX code, 
native Alpha compilers can optionally generate information that describes 
the parameters of a procedure. This auxiliary information is called procedure 
signature information, or sometimes just signature information. 


Signature information is used when a call from a native procedure passes 
control to a translated procedure and vice versa. Translated VAX code on Alpha 
processors uses a VAX argument list and function return conventions as described 
in Sections 2.4 and 2.5. Here, the signature information is used to control how 
passed and returned arguments according to Alpha conventions are manipulated 
and placed for use by translated VAX code and vice versa. 


If a procedure is compiled with signature information, PDSC$W_SIGNATURE_ 
OFFSET contains a byte offset from the procedure descriptor to the start of a 
procedure signature control block. The maximum size of the procedure 
signature control block is 72 bytes (defined by constant PSIG$K_MAX_SIZE). 
The fields defined in the procedure signature information block are illustrated in 
Figure 3-8 and described in Table 3-6. 


Figure 3-8 Procedure Signature Information Block (PSIG) 


PSIG quadword aligned 





SUMMARY REG_ARG_INFO *FRET waren epee 
<31 :28> <27:4> <3:0> _ OFFSET) 
MEMORY_ARG_INFO ARG_COUNT 4 
(for argument counts 7 to 255) <7:0> 


PSIG$K_MAX_SIZE = 72 
* FRET = PSIG$V_FUNC_RETURN 
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Table 3-6 Contents of the Procedure Signature Information Block (PSIG) 


Field Name Contents 


PSIG$V_FUNC_RETURN A 4-bit field <3:0> that describes which registers are used for the function 
value return (if there is one) and what format is used for those registers. 


Table 3-7 lists and describes the possible encoded values of PSIG$V_FUNC_ 
RETURN. 


PSIG$V_REG_ARG_INFO A 24-bit field <27:4> that is divided into six groups of four bits that correspond 
to the six arguments that can be passed in registers. These groups describe 
how each of the first six arguments are to be passed in registers of the first 
group (bits <7:4>) describing the first argument. 


Each register argument signature group is encoded as follows: 


Value 


0 
1 


9-15 


1For more specific impact on the converted field value, see Section 3.5.1. 


Name 


RASE$K_RA_NOARG 
RASE$K_RA_Q 


RASE$K_RA_I32 
RASE$K_RA_U32 
RASE$K_RA_FF 
RASE$K_RA_FD 
RASE$K_RA_FG 
RASE$K_RA_FS 


RASE$K_RA_FT 


Meaning'? 


Argument is not present 


64-bit argument passed in an integer 
register 


32-bit argument sign extended to 64 bits 
passed in an integer register 


32-bit unsigned argument zero extended 
to 64 bits passed in an integer register 


F floating argument passed in a floating- 
point register 


D_floating argument passed in a floating- 
point register 


G_floating argument passed in a floating- 
point register 


S_floating argument passed in a floating- 
point register 


T_floating argument passed in a floating- 
point register 


Reserved for future use 


2The X_floating and X_floating complex data types do not appear in this table because these types are not passed using 
the by value mechanism (see Section 3.8.5.1). 


(continued on next page) 
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Table 3-6 (Cont.) Contents of the Procedure Signature Information Block (PSIG) 


Field Name 
PSIG$V_SUMMARY 


PSIG$B_ARG_COUNT 


PSIG$V_MEMORY_ARG_ 
INFO 


Contents 


A 4-bit field <31:28> that contains coded argument signature information as 
follows: 


Bit Name Meaning 
0,1 #PSIG$M_SU_ASM Summary of arguments 7 through PSIG$B_ 
ARG_COUNT: 


00 = All arguments are 64-bit or not used 
01 = All arguments are 32-bit sign extended 


or not used 

10 = Reserved 

11 = Other (not 00 or 01) 
2 PSIG$M_SU_VLIST VAX formatted argument list expected 
3 Must be 0 (reserved) 


PSIG$M_SU_ASM values of 00 and 01 (binary) allow a quick test for the 
occurrence of either an all 32-bit or an all 64-bit argument list. The values 
for the PSIG$V_MEMORY_ARG_INFO field must be valid even when these 
occurrences apply. 


Unsigned byte (bits 0-7) that specifies the number of 64-bit argument items 
described in the argument signature information. This count includes the first 
six arguments. 


Array of 2-bit values that describe each of arguments 7 through PSIG$B_ 
ARG_COUNT. PSIG$S_MEMORY_ARG_INFO data is only defined for the 
arguments described by PSIG$B_ARG_COUNT. These memory argument 
signature bits are defined as follows: 


Value Name Meaning! 

0 MASE$K_MA_Q 64-bit argument 

1 Reserved 

2 MASE$K_MA_I32 32-bit sign-extended argument 
3 Reserved 


1For more specific impact on the converted field value, see Section 3.5.1. 


Table 3-7 Function Return Signature Encodings 


Value Name 

0 PSIG$K_FR_I64 
1 PSIG$K_FR_D64 
2 PSIG$K_FR_I32 


Meaning’? 


64-bit result in RO 
or No function result provided 
or First parameter mechanism used 


64-bit result with low 32 bits sign extended in RO and high 32 bits 
sign extended in Rl 


32-bit sign extended to 64-bit result in RO 


1For more specific impact on the converted field value, see Section 3.5.1. 


2The X_floating and X_floating complex data types do not appear in this table because these types are not passed using 
the by value mechanism (see Section 3.8.5.1). 
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Table 3-7 (Cont.) Function Return Signature Encodings 


Value 


3 
4 
5 
6 
7 
8 
9 


11 
12 
13 
14 
15 


Name 
PSIG$K_FR_U32 
PSIG$K_FR_FF 
PSIG$K_FR_FD 
PSIG$K_FR_FG 
PSIG$K_FR_FS 
PSIG$K_FR_FT 


PSIG$K_FR_FFC 
PSIG$K_FR_FDC 
PSIG$K_FR_FGC 
PSIG$K_FR_FSC 
PSIG$K_FR_FTC 


Meaning’? 

32-bit unsigned result (zero extended) in RO 
F floating result in FO 

D_floating result in FO 

G_floating result in FO 

S_floating result in FO 

T_floating result in FO 

Reserved for future use 

F_floating complex result in FO and F1 
D_floating complex result in FO and F1 
G_floating complex result in FO and F1 
S_floating complex result in FO and F1 
T_floating complex result in FO and F1 


1For more specific impact on the converted field value, see Section 3.5.1. 


2The X_floating and X_floating complex data types do not appear in this table because these types are not passed using 
the by value mechanism (see Section 3.8.5.1). 


3.5.1 Call Parameter PSIG Conversions 


Where a VAX image is translated to an Alpha image, the VAX registers RO-—15 
are represented using the lower half of the corresponding Alpha registers RO-15 — 
at call interface boundaries. No “type conversion” is performed in making 
parameters from either native or translated code available to each other. 
However, it is important to understand the effects of the PSIG field values 

when interfacing between native and translated environments. 


Note that an address under OpenVMS Alpha is described using RASE$K_RA_I32 
or MASE$K_MA_I32 as appropriate. 


3.5.1.1 Native-to-Translated Code PSIG Conversions 


The specific impact of the native-to-translated call conversions of the PSIG$V_ 
REG_ARG_INFO and the PSIG$V_FUNC_RETURN field values are listed in 


Table 3-8. 
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Table 3-8 Native-to-Translated Conversion of the PSIG Field Values 


Name Impact 


PSIG$V_REG_ARG_INFO Field Conversions 


RASE$K_RA_Q The low-order 32 bits of the integer register contents are used 


to fill the first of two longword entries in the VAX formatted 
argument list, while the high-order 32 bits are used to fill the 
second longword entry. This counts as two arguments in the VAX 
formatted argument list. 


RASE$K_RA_1I32 The low-order 32 bits of the integer register contents are used to fill 

RASE$K_RA_U382 one longword entry in the VAX formatted argument list passed to 
the translated procedure. The high-order 32 bits are ignored. This 
counts as one argument in the VAX formatted argument list. 


RASE$K_RA_FF The single-precision contents of a floating-point register are used to 
fill one longword entry in the VAX formatted argument list passed 
to the translated procedure. This counts as one argument in the 
VAX formatted argument list. The Alpha store instruction STF is 
used to place the register contents into memory. 


RASE$K_RA_FD The double-precision contents of a floating-point register are used to 

RASE$K_RA_FG fill two longword entries in the VAX formatted argument list passed 
to the translated procedure. This counts as two arguments in the 
VAX formatted argument list. The Alpha store instruction STG is 
used to place the register contents into memory. 


RASE$K_RA_FS Undefined. 
RASE$K_RA FT 
PSIGSV_MEMORY_ARG_INFO Field Conversions 


MASE$K_MA_Q These convert like the RASE$K_RA_Q and RASE$K_RA_I32 field 
MASE$K_MA_ 132 conversions, except that the Alpha argument list entry is stored in 
memory (rather than a register). 


PSIG$V_FUNC_RETURN Field Conversions 


PSIG$K_FR_I64 The translated code is returning a 64-bit result split between RO 


and R1. The low-order 32 bits of R1 are shifted left and combined 
with the low-order 32 bits of RO to form the 64-bit result that is 
returned to the native caller. 


PSIG$K_FR_D64 The translated code is returning a 64-bit result split between RO 
and R1. Both RO and R1 are sign extended from 32 to 64 bits and 
returned to the native caller in place. 


PSIG$K_FR_I82 The translated code is returning a 32-bit result in RO. RO is sign 

PSIG$K_FR_U32 extended from 32 to 64 bits and returned to the native caller in 
place. 

PSIG$K_FR_FF The single-precision contents of the result in RO is loaded into Alpha 
register FO. 

PSIG$K_FR_FD The double-precision contents in registers RO and R1 are combined 

PSIG$K_FR_FG and loaded into Alpha register FO. 

PSIG$K_FR_FS Undefined. 


PSIG$K_FR_FT 
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Table 3—8 (Cont.) Native-to-Translated Conversion of the PSIG Field Values 
Name Impact 


PSIG$V_FUNC_RETURN Field Conversions 


PSIG$K_FR_FFC The single-precision complex contents in registers RO and R1 are 
loaded into Alpha registers FO and F1. 


PSIG$K_FR_FDC The translated code is returning a double-precision complex result 
PSIG$K_FR_FGC using the hidden first parameter method (by reference). The storage 
for the result is allocated prior to the call and the address is passed 
as the extra parameter. Upon return, the result is copied from 
the temporary storage into the Alpha floating-point registers and 
returned to the native caller. 


PSIG$K_FR_FSC Undefined. 
PSIG$K_FR_FTC 


In all 64-bit cases, the longword at the lower memory address forms the earlier 

‘argument in the VAX formatted argument list. Also, for single-precision floating- 
point types, the unused 32 bits of an Alpha 64-bit argument list entry are 
undefined. 


3.5.1.2 Translated-to-Native Code PSIG Conversions 


The specific impact of the translated-to-native call conversions of the PSIG$V_ 
REG_ARG_INFO and the PSIG$V_FUNC_RETURN field values are listed in 
Table 3-9. 


Table 3-9 Translated-to-Native Conversion of the PSIG Field Values 


Name impact 
PSIG$V_REG_ARG_INFO Field Conversions 
RASE$K_RA_Q The contents of two successive longwords from the VAX formatted 


argument list are combined to form a single quadword value that is 
placed in an integer register. This counts as one argument in the 
Alpha argument list. 


RASE$K_RA_I32 The contents of one longword entry from the VAX formatted 
RASE$K_RA_U82 argument list is sign extended and placed in the integer register. 
This counts as one argument in the Alpha argument list. 


RASE$K_RA_FF A single longword entry from the VAX formatted argument list is 
used to form a floating-point value in a floating-point register. This 
counts as one argument in the Alpha argument list. The Alpha load 
instruction LDF is used to place the argument in the floating-point | 
register. 


RASE$K_RA_FD Two longword entries from the VAX formatted argument list are 

RASE$K_RA_FG combined to form a single floating-point value in a floating-point 
register. This counts as one argument in the Alpha argument list. 
The Alpha load instruction LDG is used to place the argument in 
the floating-point register. 


RASE$K_RA_FS Undefined. 
RASE$K_RA_FT 


(continued on next page) 
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Table 3-9 (Cont.) Translated-to-Native Conversion of the PSIG Field Values 


Name 


Impact 


PSIG$V_MEMORY_ARG_INFO Field Conversions 


MASE$K_MA_Q 


MASE$K_MA_I32 


These convert like RASE$K_RA_Q and RASE$K_RA_I32 field 
conversions, except that the Alpha argument list entry is stored in 
memory (rather than a register). 


PSIG$V_FUNC_RETURN Field Conversions 


PSIG$K_FR_I64 


PSIG$K_FR_D64 


PSIG$K_FR_I32 
PSIG$K_FR_U32 


PSIG$K_FR_FF 


PSIG$K_FR_FD 
PSIG$K_FR_FG 


PSIG$K_FR_FS 
PSIG$K_FR_FT 


PSIG$K_FR_FFC 


PSIG$K_FR_FDC 
PSIG$K_FR_FGC 


PSIG$K_FR_FSC 
PSIG$K_FR_FTC 


The native code is returning a 64-bit result in RO. The high 32 bits 
of RO are moved to the low half of Rl and sign extended, and then 
RO is sign extended from 32 to 64 bits. The 64-bit result is then 
returned to the translated caller in RO and R1. 


The native code is returning a 64-bit result split between RO and 
R1. Both RO and R1 are sign extended from 32 to 64 bits and 
returned to the translated caller in place. 


The native code is returning a 32-bit result in RO. RO is sign 
extended from 32 to 64 bits and the result is then returned in place 
to the translated caller. 


The single-precision result in Alpha register FO is stored in the 
low-order half of register RO.* 


The double-precision result in Alpha register FO is stored in the 
low-order halves of registers RO and R1. 


Undefined. 


The single-precision complex results in Alpha registers FO and F1 is 
stored in the low-order halves of registers RO and R1.! 


The native code is returning a double-precision complex result in the 
Alpha floating-point registers. The result is copied into the storage 
given by the hidden first parameter passed by the translated caller. 


Undefined. 


1Note that for single-precision floating-point types, the unused 32 bits of an Alpha 64-bit argument 


list entry are undefined. 


3.5.2 Default Procedure Signature 


In certain cases, a standard default procedure signature representing a common 
combination of characteristics is encoded in a special manner. (For example, see 
the descriptions of PDSC$W_SIGNATURE_OFFSET in Sections 3.4.1 and 3.7.4.) 


In the OpenVMS Alpha environment, procedure signatures are used only to effect 
interoperation between native OpenVMS Alpha and translated VAX VMS or 
OpenVMS VAX images. Default procedure signature characteristics are defined 
for each of the two possible call situations. 


For an OpenVMS Alpha procedure that is callable from a translated VAX 
procedure, a default procedure signature implies the following characteristics 
about the expected parameters and result of a call to that procedure: 
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¢ The number of parameters passed is contained in the AI (R25) register (taken 
from the count in the VAX argument list). 


e All parameters (if any) are 32-bit sign extended (RASE$K_RA_I32 for register 
arguments, MASE$K_MA_ 132 for memory arguments). 
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e¢ The function result (if any) is 32-bit sign extended (PSIG$K_FR_I32). 


For a bound procedure used as a jacket to effect a call into a translated image, a 
default procedure signature implies the following characteristics about the actual 
parameters and the expected result from a call to that translated procedure: 


e The number of parameters passed is contained in the AI (R25) register. 

e The register parameters (if any) are described in the AI register. 

e The memory parameters (if any) are 32-bit sign extended (MASE$K_MA_I382). 
¢ The function result (if any) is 32-bit sign extended (PSIG$K_FR_I32). 


3.6 Procedure Call Chain 


Except for the first invocation in a thread, there is always an invocation that 
was previously considered to be the current procedure invocation. The current 
procedure invocation, together with the previous current procedure invocations, 
together with all successive previously current procedure invocations, all the way 
back to the first invocation in the thread, make up a logical list of procedure 
contexts referred to as the call chain. The current procedure invocation is 
always considered to be the first procedure invocation in this logical list and the 
first procedure invocation executed in the thread is always the last procedure 
invocation in the list. The register values of all nonscratch registers at the time of 
the currently active call in a procedure invocation can be determined by walking 
the call chain and retrieving the procedure invocation context for that invocation. 
A procedure is called an active procedure (active invocation) while it exists on 
the call chain. 


The call chain and its supporting data are used by code that implements various 
aspects of the calling standard such as call returns and procedure unwinding. 


3.6.1 Current Procedure 


In this calling standard, R29 is the frame pointer (FP) register that defines the 
current procedure. 


Therefore, the current procedure must always maintain in FP one of the following 
pointer values: 


.® Pointer to the procedure descriptor for that procedure 


¢ Pointer to a naturally aligned quadword containing the address of the 
procedure descriptor for that procedure. For purposes of finding a procedure’s 
procedure descriptor, no assumptions must be made about the quadword 
location. As long as all other requirements of this standard are met, a 
compiler is free to use FP as a base register for any arbitrary storage, 
including a stack frame, provided that while the procedure is current, 
the quadword pointed to by the value in FP contains the address of that 
procedure’s descriptor. 


At any point in time, the FP value can be interpreted to find the procedure 
descriptor for the current procedure by examining the value at O(FP) as follows: 


e § =6If 0(FP)<2:0> = 0, then FP points to a quadword that contains a pointer to 
the procedure descriptor for the current procedure. 


e =6If 0(FP)<2:0> # 0, then FP points to the procedure descriptor for the current 
procedure. 
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By examining the first quadword of the procedure descriptor, the procedure type 
can be determined from the PDSC$V_KIND field. 


The following code is an example of how the current procedure descriptor and 
procedure type can be found: 


LDQ RO,0(FP) ;Fetch quadword at FP 

AND RO,#7,R28 ;Mask alignment bits 

BNEQ R28,20$ ;Is procedure descriptor pointer 

LDQ RO, 0(RO0) ;Was pointer to procedure descriptor 
10S: AND RO, #7,R28 +Do sanity check 

BNEQ R28,20$ sAll is well 

*Error - Invalid FP 
208: AND RO, #15,R0 *Get kind bits 


+Procedure KIND is now in RO 


IF PDSC$V_KIND is equal to PDSC$K_KIND_FP_STACK, the current procedure 
has a stack frame. 


If PDSC$V_KIND is equal to PDSC$K_KIND_FP_REGISTER, the current 
procedure is a register frame procedure. 


Hither type of procedure can use either type of mechanism to point to the 
procedure descriptor. Compilers may choose the appropriate mechanism to use 
based on the needs of the procedure involved. 


3.6.2 Procedure Call Tracing 


Mechanisms for each of the following functions are needed to support procedure 
call tracing: 


¢ To provide the context of a procedure invocation 
e To walk (navigate) the procedure call chain 
¢ To refer to a given procedure invocation 


This section describes the data structure mechanisms. The routines that support 
these functions are described in Section 3.6.3. 


3.6.2.1 Referring to a Procedure Invocation from a Data Structure 
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When referring to a specific procedure invocation at run time, a procedure 
invocation handle, shown in Figure 3-9, can be used. Defined by constant 
LIBICB$K_INVO_HANDLE_SIZE, the structure is a single-field longword called 
HANDLE. HANDLE describes the invocation handle of the procedure. 


Figure 3-9 Procedure Invocation Handle Format 


longword aligned 


HANDLE 2 


INVO_HANDLE_SIZE = 4 
ZK-4656A-GE 


To encode a procedure invocation handle, follow these steps: 


1. If PDSC$V_BASE_REG_IS_FP is set to 1 in the corresponding procedure 
descriptor, then set INVO_HANDLE to the contents of the FP register in that 
invocation. 
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If PDSC$V_BASE_REG_IS_FP is set to 0, set INVO_HANDLE to the contents 
of the SP register in that invocation. (That is, start with the base register 
value for the frame.) 


2. Shift the INVO_HANDLE contents left one bit. Because this value is initially 
known to be octaword aligned (see Section 3.7.1), the result is a value whose 
5 low-order bits are zero. 


3. If PDSC$V_KIND = PDSC$K_KIND_FP_STACK, perform a logical OR on 
the contents of INVO_HANDLE with the value 1Fj,, and then set INVO_ 
HANDLE to the value that results. 


If PDSC$V_KIND = PDSC$K_KIND_FP_REGISTER, perform a logical OR on 
the contents of INVO_HANDLE with the contents of PDSC$B_SAVE_RA, and 
then set INVO_HANDLE to the value that results. 


Note that a procedure invocation handle is not defined for a null frame procedure. 


Note 


So you can distinguish an invocation of a register frame procedure that 
calls another register frame procedure (where the called procedure uses no 
stack space and therefore has the same base register value as the caller), 
the register number that saved the return address is included in the 
invocation handle of a register frame procedure. Similarly, the number 
3119 in the invocation handle of a stack frame procedure is included to 
distinguish an invocation of a stack frame procedure that calls a register 
frame procedure where the called procedure uses no stack space. 


3.6.2.2 Invocation Context Block 
The context of a specific procedure invocation is provided through the use of 
a data structure called an invocation context block. The minimum size of 
the block is 528 bytes and is system defined using the constant LIBICB$K_ 
INVO_CONTEXT_BLK_SIZE. The size of the last field (LIBICB$Q SYSTEM_ 
DEFINED[n]) defined by the host system determines the total size of the block. 


The fields defined in the invocation context block are illustrated in Figure 3-10 
and described in Table 3-10. 
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Figure 3-10 Invocation Context Block Format 


INVO_CONTEXT_BLK quadword aligned 


CONTEXT_LENGTH } 
BLOCK_VERSION FRAME_FLAGS , 


PROCEDURE_DESCRIPTOR 












716 
PROGRAM_COUNTER 


124 








PROCESSOR_STATUS 


FREG[ 30 ] 


132 






:40 





‘64 


:72 


:280 


504 


512 
SYSTEM_DEFINED 





LIBICBS$K_INVO_CONTEXT_BLK_SIZE is defined by the system. 
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Table 3-10 Contents of the Invocation Context Block 


- Field Name 
LIBICB$L_CONTEXT_LENGTH 


LIBICB$R_FRAME_FLAGS 


LIBICB$B_BLOCK_VERSION 
LIBICB$PH_PROCEDURE_ 


DESCRIPTOR 
LIBICB$Q_PROGRAM_COUNTER 


LIBICB$Q_PROCESSOR_STATUS 
LIBICB$Q_IREG(n] 


LIBICB$Q_FREG[7] 


LIBICB$Q_SYSTEM_DEFINED{[n] 


Contents 


Unsigned count of the total length in bytes of the context block; this 
represents the sum of the lengths of the standard-defined portion 
and the system-defined section. 


The procedure frame flag bits <24:0> are defined as follows: 


LIBICB$V_ Bit 0. If set to 1, the invocation context 
EXCEPTION_ corresponds to an exception frame. 
FRAME 

LIBICB$V_AST_ Bit 1. If set to 1, the invocation context 
FRAME corresponds to an asynchronous trap. 
LIBICB$V_ Bit 2. If set to 1, the invocation context 
BOTTOM_OF_ corresponds to a frame that has no 
STACK predecessor. 

LIBICB$V_BASE_ __ Bit 3. If set to 1, the BASE_FRAME bit 
FRAME is set in the FLAGS field of the associated 


procedure descriptor. 


A byte that defines the version of the context block. Since this block 
is currently the first version, the value is set to 1. 


Address of the procedure descriptor for this context. 


Quadword that contains the current value of the procedure’s 
program counter. For interrupted procedures, this is the same 

as the continuation program counter; for active procedures, this is 
the return address back into that procedure. 


Contains the current value of the processor status. 


Quadword that contains the current value of the integer register in 
the procedure (where n is the number of the register). 


Quadword that contains the current value of the floating-point 
register in the procedure (where n is the number of the register). 


A variable-sized area with locations defined in quadword 
increments by the host environment that contains procedure context 
information. These locations are not defined by this standard. 


3.6.2.3 Getting a Procedure Invocation Context with a Routine 
A thread can obtain its own context or the current context of any procedure 
invocation in the current call chain (given an invocation handle) by calling the 
run-time library functions defined in Section 3.6.3. 


3.6.2.4 Walking the Call Chain 


During the course of program execution, it is sometimes necessary to walk the 
call chain. Frame-based exception handling is one case where this is done. Call 
chain navigation is possible only in the reverse direction (in a latest-to-earliest or 
top-to-bottom procedure). 


To walk the call chain, perform the following steps: 


1. Build an invocation context block when given a program state (which contains 


a register set). 


For the current routine, an initial invocation context block can be obtained by 
calling the LIB$GET_CURR_INVO_CONTEXT routine (see Section 3.6.3.2). 
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2. Repeatedly call the LIB{GET_PREV_INVO_CONTEXT routine (see 
Section 3.6.3.3) until the end of the chain has been reached (as signified 
by 0 being returned). 


Compilers are allowed to optimize high-level language procedure calls in such 
a way that they do not appear in the invocation chain. For example, inline 
procedures never appear in the invocation chain. 


Make no assumptions about the relative positions of any memory used for 
procedure frame information. There is no guarantee that successive stack frames 
will always appear at higher addresses. 


3.6.3 Invocation Context Access Routines 


A thread can manipulate the invocation context of any procedure in the thread’s 
virtual address space by calling the following run-time library functions. 


3.6.3.1 LIBS$GET_INVO_CONTEXT 


A thread can obtain the invocation context of any active procedure by using the 
following function format: 


LIB$GET_INVO_CONTEXT(invo_handle, invo_context) 


Argument OpenVMS Usage Type Access Mechanism 
invo_handle _invo_handle longword (unsigned) read by value 
invo_context invo_context_blk structure write by reference 
Arguments: 


invo_handle 
Handle for the desired invocation. 


invo_context 
Address of an invocation context block into which the procedure context of the frame 
specified by invo_handle will be written. 


Function Value Returned: 
status 
Status value. A value of 1 indicates success; a value of 0 indicates failure. 


Note 


If the invocation handle that was passed does not represent any procedure 
context in the active call chain, the value of the new contents of the 
context block is unpredictable. 


3.6.3.2 LIB$GET_CURR_INVO_CONTEXT 


A thread can obtain the invocation context of a current procedure by using the 
following function format: 


LIB$GET_CURR_INVO_CONTEXT(invo_context) 
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Argument OpenVMS Usage Type Access Mechanism 


invo_context invo_context_blk structure write by reference 


Argument: 


invo_context 
Address of an invocation context block into which the procedure context of the caller 
will be written. 


Function Value Returned: 


None. To facilitate use in the implementation of the C language unwind setjmp or 
longjump function (only), the routine sets RO to 0. 


3.6.3.3 LIBSGET_PREV_INVO_CONTEXT 
A thread can obtain the invocation context of the procedure context preceding any 
other procedure context by using the following function format: 


LIB$GET_PREV_INVO_CONTEXT(invo_context) 


Argument OpenVMS Usage Type Access Mechanism 
invo_context invo_context_blk structure modify by reference 
Argument: 


invo_context 
Address of an invocation context block. The given context block is updated to 
represent the context of the previous (calling) frame. 


For the purposes of this function, the minimum fields of an invocation block that 
must be defined are those IREG and FREG fields corresponding to registers used by 
a context whether the registers are preserved or not. Note that the invocation context 
blocks written by the routines specified in these sections define all possible fields in a 
context block. Such context blocks satisfy this minimum requirement. 


Function Value Returned: 


status 

Status value. A value of 1 indicates success. When the initial context represents the 
bottom of the call chain, a value of 0 is returned. If the current operation completed 
without error, but a stack corruption was detected at the next level down, a value of 3 
is returned. 


3.6.3.4 LIBS$GET_INVO_HANDLE 
A thread can obtain an invocation handle corresponding to any invocation context 
block by using the following function format: 


LIB$GET_INVO_HANDLE(invo_context) 


Argument OpenVMS Usage Type Access Mechanism 
invo_context invo_context_blk structure read by reference 
Argument: 


invo_context 
Address of an invocation context block. Here, only the frame pointer and stack pointer 
fields of an invocation context block must be defined. 
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Function Value Returned: 


invo_handle 
Invocation handle of the invocation context that was passed. If the returned value is 
LIB$K_INVO_HANDLE_NULL, the invocation context that was passed was invalid. 


3.6.3.5 LIB$GET_PREV_INVO_HANDLE 


A thread can obtain an invocation handle of the procedure context preceding that 
of a specified procedure context by using the following function format: 


LIB$GET_PREV_INVO_HANDLE(invo_handle) 


Argument OpenVMS Usage Type Access Mechanism 
invo_handle invo_handle longword (unsigned) read by value 
Argument: 


invo_handle 
An invocation handle that represents a target invocation context. 


Function Value Returned: 


invo_handle 
An invocation handle for the invocation context that is previous to that which was 
specified as the target. 


3.6.3.6 LIBSPUT_INVO_REGISTERS 
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A given procedure invocation context’s fields can be updated with new register 
contents by calling a system library function in following format: 


LIB$PUT_INVO_REGISTERS(invo_handle, invo_context, invo_mask) 


Argument OpenVMS Usage Type Access Mechanism 
invo_handle  invo_handle longword (unsigned) read by value 
invo_context invo_context_blk structure read by reference 
invo_mask mask_quadword quadword (unsigned) read by reference 
Arguments: 


invo_handle 
Handle for the invocation to be updated. 


invo_context 
Address of an invocation context block that contains new register contents. 


Each register that is set in the invo_mask parameter is updated using the value 
found in the corresponding IREG or FREG field. The program counter and processor 
status of the given invocation can also be updated in this way. No other fields of the 
invocation context block are used. 


invo_mask 

Address of a 64-bit bit vector, where each bit corresponds to a register field in the 
passed invo_context. Bits 0 through 30 correspond to IREG[0] through IREG[30], bit 
31 corresponds to PROGRAM_COUNTER, bits 32 through 62 correspond to FREG[0] 
through FREG[30], and bit 63 corresponds to PROCESSOR_STATUS. 
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Function Value Returned: 


status 
Status value. A value of 1 indicates success. When the initial context represents the 
bottom of the call chain, a value of 0 is returned. 


Caution 


While this routine can be used to update the stack pointer (SP) and frame 
pointer (FP), great care must be taken to assure that a valid stack frame 
and execution environment result; otherwise, execution may become 
unpredictable. 


3.7 Transfer of Control 


This standard states that a standard call may be accomplished in any way that 
presents the called routine with the required environment (see Section 1.4). 
However, typically, most standard-conforming external calls are implemented 
with a common sequence of instructions and conventions. Since a common set of 
call conventions is so pervasive, these conventions are included for reference as 
part of this standard. 


One important feature of the calling standard is that the same instruction 
sequence can be used to call each of the different types of procedure. Specifically, 
the caller does not have to know which type of procedure is being called. 


3.7.1 Call Conventions 


The call conventions describe the rules and methods used to communicate certain 
information between the caller and the called procedure during invocation and 
return. For a standard call, these conventions include the following: 


e Procedure value 


The calling procedure must pass to the called procedure its procedure value. 
This value can be a statically or dynamically bound procedure value. This 
is accomplished by loading R27 with the procedure value before control is 
transferred to the called procedure. 


e Return address 


The calling procedure must pass to the called procedure the address to which 
control must be returned during a normal return from the called procedure. 
In most cases, the return address is the address of the instruction following 
the one that transferred control to the called procedure. For a standard call, 
this address is passed in the return address register (R26). 


e Argument list 


The argument list is an ordered set of zero or more argument items that 
together comprise a logically contiguous structure known as an argument 
item sequence. This logically contiguous sequence is typically mapped to 
registers and memory in a way that produces a physically discontiguous 
argument list. In a standard call, the first six items are passed in registers 
R16-21 or registers F16—21. (See Section 3.8.2 for details of argument-to- 
register correspondence.) The remaining items are collected in a memory 
argument list that is a naturally aligned array of quadwords. In a standard 
call, this list (if present) must be passed at O(SP). 
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¢ Argument information 


The calling procedure must pass to the called procedure information about 
the argument list. This information is passed in the argument information 
(AI) register (R25). Defined by AI$K_AI_SIZE, the structure is a quadword as 
shown in Figure 3-11 with the fields described in Table 3-11. 


Figure 3-11 Argument Information Register (R25) Format 


ARG_REG_INFO ARG_COUNT 
<31:26> <25:8> <7:0> 


31 





Must be 0 . 
Al_SIZE =8 
ZK-4659A-GE 
Table 3-11 Contents of the Argument Information Register (R25) 
Field Name Contents 
AI$B_ARG_COUNT Unsigned byte <7:0> that specifies the number of 64-bit argument items in the 


argument list (known as the “argument count”). 


AI$V_ARG_REG_INFO An 18-bit vector field <25:8> divided into six groups of three bits that correspond 


to the six arguments passed in registers. These groups describe how each of the 


first six arguments are passed in registers with the first group <10:8> describing 
the first argument. The encoding for each group for the argument register usage 


follows: 


Value Name 


0 AI$K_AR_164 


AI$K_AR_FF 
AI$K_AR_FD 
AI$K_AR_FG 
AI$K_AR_FS 
AI$K_AR_FT 


ow#»r wond 


~J 


Bits 26-63 Reserved and must be 0. 


e Function result 


Meaning 


64-bit or 32-bit sign-extended to 64-bit argument 
passed in an integer register 
or Argument is not present 


F_floating argument passed in a floating register 
D_floating argument passed in a floating register 
G_floating argument passed in a floating register 
S_floating argument passed in a floating register 
T_floating argument passed in a floating register 


Reserved 


If a standard-conforming procedure is a function and the function result is 
returned in a register, then the result is returned in RO, FO, or FO and F1. 
Otherwise, the function result is returned via the first argument item or 
dynamically as defined in Section 3.8.7. 
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e Stack usage 


At any time, the stack pointer (SP) must.denote an address that has the 
minimum alignment required by the Alpha hardware. In addition, whenever 
control is transferred to another procedure, the stack must be octaword 
aligned. (A side effect of this is that the in-memory portion of the argument 
list will start on an octaword boundary.) During a procedure invocation, the 
SP (R30) can never be set to a value higher than the value of SP at entry to 
that procedure invocation. 


The contents of the stack located above the portion of the argument list that is 
passed in memory (if any) belongs to the calling procedure and is, therefore, 
not to be read or written by the called procedure, except as specified by 
indirect arguments or language-controlled up-level references. 


Since SP is used by the hardware in raising exceptions and asynchronous . 
interrupts, the contents of the next 2048 bytes below the current SP value 
are continually and unpredictably modified. Software that conforms to this 
standard must not depend on the contents of the 2048 stack locations below 
O(SP). 


Note 


One implication of the stack alignment requirement is that low-level 
interrupt and exception-fielding software must be prepared to handle and 
correct the alignment before calling handler routines, in case the stack 
pointer is not octaword aligned at the time of an interrupt or exception. 


3.7.2 Linkage Section 


Because the Alpha hardware architecture has the property of instructions 

that cannot contain full virtual addresses, it is sometimes referred to as a 

base register architecture. In a base register architecture, normal. memory 
references within a limited range from a given address are expressed by using 
displacements relative to the contents of a register containing that address (base 
register). Base registers for external program segments, either data or code, are 
usually loaded indirectly through a program segment of address constants. 


The fundamental program section containing address constants that a procedure 
uses to access other static storage, external procedures, and variables is termed a 
linkage section. Any register used to access the contents of the linkage section 
is termed a linkage pointer. 


A procedure’s linkage section includes the procedure descriptor for the procedure, 
addresses of all external variables and procedures referenced by the procedure, 
and other constants a compiler may choose to reference using a linkage pointer. 


When a standard procedure is called, the caller must provide the procedure value 
for that procedure in R27. Static procedure values are defined to be the address 
of the procedure’s descriptor. Since the procedure descriptor is part of the linkage 
section, calling this type of procedure value provides a pointer into the linkage 
section for that procedure in R27. This linkage pointer can then be used by the 
called procedure as a base register to address locations in its linkage section. For 
this reason, most compilers generate references to items in the linkage section as 
offsets from a pointer to the procedure’s descriptor. 
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Compilers usually arrange (as part of the environment setup) to have the 
environment setup code (for bound procedures) load R27 with the address of 
the procedure’s descriptor so it can be used as a linkage pointer as previously 
described. For an example, see Section 3.7.4. 


Although not required, linkages to external procedures are typically represented 
in the calling procedure’s linkage section as a linkage pair. As shown in 
Figure 3-12 and described in Table 3-12, a linkage pair (LKP) block with two 
fields should be octaword aligned and defined by LKP$K_SIZE as 16 bytes. 


Figure 3-12 Linkage Pair Block Format 


LKP octaword aligned 


PROC_VALUE 





LKP$K_SIZE = 16 


ZK-4660A-GE 
Table 3-12 Contents of the Linkage Pair Block 
Field Name Contents 
LKP$Q_ENTRY Absolute address of the first instruction of the called 


procedure’s entry code sequence. 


LKP$Q_PROC_VALUE Contains the procedure value of the procedure to be called. 
Normally, this field is the absolute address of a procedure 
descriptor for the procedure to be called, but in certain cases, it 
could be a bound procedure value (such as for procedures that 
are called through certain types of transfer vectors). 


In general, an object module contains a procedure descriptor for each entry 
point in the module. The descriptors are allocated in a linkage section. For each 
external procedure Q that is referenced in a module, the module’s linkage section 
also contains a linkage pair denoting Q (which is a pointer to Q’s procedure 
descriptor and entry code address). 


The following code example calls an external procedure Q as represented by 
a linkage pair. In this example, R4 is the register that currently contains the 
address of the current procedure’s descriptor. 


LDQ R26,Q DESC-MY DESC(R4) 7Q’s entry address into R26 

LDQ R27,Q DESC-MY DESC+8(R4) ;Q’s procedure value into R27 

MOVQ #AI LITERAL,R25 ;Load Argument Information register 
JSR R26, (R26) ;Call to Q. Return address in R26 
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Because Q’s procedure descriptor (statically defined procedure value) is in Q’s 
linkage section, Q can use the value in R27 as a base address for accessing data 
in its linkage section. Q accesses external procedures and data in other program 
sections through pointers in its linkage section. Therefore, R27 serves as the root 
pointer through which all data can be referenced. 


3.7.3 Calling Computed Addresses 


Most calls are made to a fixed address whose value is determined by the time 
the program starts execution. However, certain cases are possible that cause the 
exact address to be unknown until the code is finally executed. In this case, the 
procedure value representing the procedure to be called is computed in a register. 


The following code example illustrates a call to a computed procedure value 
(simple or bound) that is contained in R4: 


LDQ R26,8(R4) ;Entry address to scratch register 
MOV R4,R27 ;Procedure value to R27 

MOVOQ #AI_LITERAL,R25 ;Load Argument Information register 
JSR R26, (R26) ;Call entry address. 


If interoperation with translated images must be considered, the procedure value 
(in this example, in R4) might be the address of a VAX entry point rather than the 
address of an Alpha procedure descriptor. A VAX entry point can be dynamically 
distinguished from an Alpha procedure descriptor by examining bits 12 and 13 of 
a VAX entry call mask, which are required to be 0 by the VAX architecture. For 
an Alpha procedure, bit 12 corresponds to the PDSC$V_NATIVE flag, which is 
required to be set in all Alpha procedure descriptors. Bit 13 corresponds to the 
PDSC$V_NO_JACKRHT flag, which is currently required to be set but reserved for 
enhancements to this standard in all Alpha procedure descriptors. 


If the procedure value is determined to correspond to an Alpha procedure, then 
the call can be completed as discussed. If the procedure value is determined to 
correspond to a VAX procedure, then the call must be completed using system 
facilities that will effect the transition into and out of the code of the translated 
image. Example 3-1 illustrates a code sequence for examining the procedure | 
value. 


Example 3—1 Code for Examining the Procedure Value 


LDL R28,0(R4) sLoad the flags field of the target PDSC 
MOVQ #AI LITERAL,R25 sLoad Argument Information register 

SRL R28, #PDSCSV_NO JACKET, R26 ;Position jacket flag 

BLBC R26,CALL_ JACKET ;If clear then jacket needed 

LDQ R26,8(R4) ;Entry address to scratch register 

MOV R4,R27 +Procedure value to R27 

JSR R26, (R26) Call entry address. 


back_in line: 
ees ;Rest of procedure code goes here 
TRANSLATED: Generated out of line, R2 contains a 


LDQ R26,N_TO T LKP(R2) ;Entry address to scratch register 
LDQ R27,N_TO_T LKP+8(R2) ;Load procedure value 


MOV R4,R23 ;Address of routine to call to R23 
JSR R26, (R26) ;Call jacket routine 
BR back_in line ;Return to normal code path 


(continued on next page) 
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Example 3-1 (Cont.) Code for Examining the Procedure Value 


CALL JACKET: H 
~ SRL R28, #PDSC$V_NATIVE,R28;Jacketing for translated or native? 
LDA R24,PSIG OUT(R2) ;Pass address of our argument 
~ + signature information in R24 
BLBC R28, TRANSLATED ;If clear, then translated jacketing 
(Native Jacketing Reserved for Future Use) 
BR back_in_ line ;Return to normal code path 


In Example 3-1, jacketing functionality is provided by the SYS$NATIVE_ 
TO_TRANSLATED routine. This system procedure is called with the actual 
arguments for the target procedure in their normal locations (as though the 
target procedure were an Alpha procedure) and with two additional, nonstandard 
arguments in registers R23 and R24. R23 contains the procedure value for the 
target VAX procedure, and R24 contains the address of a procedure signature 
block for this call as described in Section 3.5. 


3.7.4 Bound Procedure Descriptors 
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Bound procedure descriptors provide a mechanism to interpose special 
processing between a call and the called routine without modifying either. The 
descriptor may contain (or reference) data used as part of that processing. 
Between native and translated images, the OpenVMS Alpha operating system 
uses linker and image-activator created bound procedure descriptors to mediate 
the handling of parameter and result passing (see Section 3.5). Language 
processors on OpenVMS Alpha systems use bound procedure descriptors to 
implement bound procedure values (see Section 3.7.4.1). Other uses are possible. 


The minimum size of the descriptor is 24 bytes (defined by PDSC$K_MIN_ 
BOUND_SIZE). An optional PDSC extension in 8-byte increments provides the 
specific environment values as defined by the implementation. 


The fields defined in the bound procedure descriptor are illustrated in Figure 3-13 
and described in Table 3-13. 
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Figure 3-13 Bound Procedure Descriptor (PDSC) 


PDSC | quadword aligned 


<15:12> | <11:8> 


ENTRY 
PROC_VALUE 


PDSC$K_MIN_BOUND_SIZE = 24 
End of required part of procedure descriptor 






18 


124 
ENVIRONMENT 


*FRET = PDSC$V_FUNC_RETURN 
ZK-4662A-GE 


Table 3-13 Contents of the Bound Procedure Descriptor (PDSC) 


Field Name 


Contents 


PDSC$W_FLAGS Vector of flag bits <15:0> that must be a copy of the flag bits (except for KIND | 


PDSC$V_FUNC_ 
RETURN 


Bits 12-15 


bits) contained in the quadword pointed to by PDSC$Q_PROC_VALUE. 


PDSC$V_KIND A 4-bit field <3:0> that identifies the type of procedure 
descriptor. For a procedure with bound values, this field 
must specify a value of 0. 


A 4-bit field <11:8> that describes which registers are used for the function 
value return (if there is one) and what format is used for those registers. 


PDSC$V_FUNC_RETURN in a bound procedure descriptor must be the same 
as the PDSC$V_FUNC_RETURN of the procedure descriptor for the procedure 
for which the environment is established. 


Table 3—7 lists and describes the possible encoding values of PDSC$V_FUNC_ 
RETURN. 


Reserved and must be 0. 


(continued on next page) 
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Table 3-13 (Cont.) Contents of the Bound Procedure Descriptor (PDSC) 


Field Name 


Contents 


PDSC$W_SIGNATURE__ A 16-bit signed byte offset from the start of the procedure descriptor. This 


OFFSET 


offset designates the start of the procedure signature block (if any). In a bound 
procedure, a zero in this field indicates the actual signature block must be 
sought in the procedure descriptor indicated by the PDSC$Q_PROC_VALUE 
field. A 1 in this field indicates a standard default signature. (An offset value 
of 1 is not a valid offset because both procedure descriptors and signature 
blocks must be quadword aligned. See Section 3.5 for details of the procedure 
signature block.) 


Note that a nonzero signature offset in a bound procedure value normally occurs 
only in the case of bound procedures used as part of the implementation of 
calls from native OpenVMS Alpha code to translated OpenVMS VAX images. 

In any case, if a nonzero offset is present, it takes precedence over signature 
information that might occur in any related procedure descriptor. 


PDSC$Q_ENTRY Address of the transfer code sequence. 
PDSC$Q_PROC_VALUE Value of the procedure to be called by the transfer code. The value can be either 


the address of a procedure descriptor for the procedure or possibly another 
bound procedure value. | 


PDSC$Q_ An environment value to pass to the procedure. The choice of environment value 
ENVIRONMENT is system implementation specific. For more information, see Section 3.7.4.1. 


3.7.4.1. Bound Procedure Value 


There are two distinct classes of procedures: 
° Simple procedure 
e Bound procedure 


A simple procedure is a procedure that does not need direct access to the stack 
of its execution environment. A bound procedure is a procedure that does need 
direct access to the stack of its execution environment, typically to reference 

an up-level variable or to perform a nonlocal GOTO operation. Both a simple 
procedure and a bound procedure have an associated procedure descriptor, as 
described in previous sections. 


When a bound procedure is called, the caller must pass some kind of pointer to 
the called code that allows it to reference its up-level environment. Typically, 
this pointer is the frame pointer for that environment, but many variations are 
possible. When the caller is executing its program within that outer environment, 
it can usually make such a call directly to the code for the nested procedure 
without recourse to any additional procedure descriptors. However, when 

a procedure value for the nested procedure must be passed outside of that 
environment to a call site that has no knowledge of the target procedure, a 
bound procedure descriptor is created so that the nested procedure can be called 
just like a simple procedure. 


Bound procedure values, as defined by this standard, are designed for 
multilanguage use and utilize the properties of procedure descriptors to 
allow callers of procedures to use common code to call both bound and simple 
procedures. 


The procedure value for a bound procedure is a pointer to a bound procedure 
descriptor that, like all other procedure descriptors, contains the address to which 
the calling procedure must transfer control at offset 8 (see Figure 3-13). This 
transfer code is responsible for setting up the dynamic environment needed 
by the target nested procedure and then completing the transfer of control to 
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the code for that procedure. The transfer code receives in R27 a pointer to 

its corresponding bound procedure descriptor and thus can fetch any required 
environment information from that descriptor. A bound procedure descriptor also 
contains a procedure value for the target procedure that is used to complete the 
transfer of control. 


When the transfer code sequence addressed by PDSC$Q_ENTRY of a bound 
procedure descriptor is called (by a call sequence such as the one given in 
Section 3.7.3), the procedure value will be in R27, and the transfer code must 
finish setting up the environment for the target procedure. The preferred location 
for this transfer code is directly preceding the code for the target procedure. This 
saves a memory fetch and a branching instruction and optimizes instruction 
caches and paging. 


The following is an example of such a transfer code sequence. It is an example of 
a target procedure Q that expects the environment value to be passed in R1 and 
a linkage pointer in R27. 


Q TRANSFER: 
LDQ R1,24(R27) ;Environment value to Rl 
LDQ R27,16(R27) ;Procedure descriptor address to R27 
Q ENTRY:: ;Normal procedure entry code starts here 


After the transfer code has been executed and control is transferred to Q’s entry 
address, R27 contains the address of Q’s procedure descriptor, R26 (unmodified 
by transfer code) contains the return address, and R1 contains the environment 
value. 


When a bound procedure value such as this is needed, the bound procedure 
descriptor is usually allocated on the parent procedure’s stack. 


3.7.5 Entry and Exit Code Sequences 


To ensure that the stack can be interpreted at any point during thread execution, 
all procedures must adhere to certain conventions for entry and exit as defined in 
this section. 


3.7.5.1 Entry Code Sequence 
Since the value of FP defines the current procedure, all properties of the 
environment specified by a procedure’s descriptor must be valid before the FP 
is modified to make that procedure current. In addition, none of the properties 
specified in the calling procedure’s descriptor may be invalidated before the called 
procedure becomes current. So, until the FP has been modified to make the 
procedure current, all entry code must adhere to the following rules: 


e All registers specified by this standard as saved across a standard call must 
contain their original (at entry) contents. 


e No standard calls may be made. 


Note 


If an exception is raised or if an exception occurs in the entry code of a 
procedure, that procedure’s exception handler (if any) will not be invoked 
since the procedure is not current yet. Therefore, if a procedure has 

an exception handler, compilers may not move code into the procedure 
prologue that might cause an exception that would be handled by that 
handler. 
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When a procedure is called, the code at the entry address must synchronize 
(as needed) any pending exceptions caused by instructions issued by the caller, 
must save the caller’s context, and must make the called procedure current by 
modifying the value of FP as described in the following steps: 


1. If PDSC$L_SIZE is not 0, set register SP = SP — PDSC$L_SIZE. 


2. If PDSC$V_BASE_REG_IS_FP is 1, store the address of the procedure 
descriptor at O(SP). 


If PDSC$V_KIND = PDSC$K_KIND_FP_REGISTER, copy the return address 
to the register specified by PDSC$B_SAVE_RA, if it is not already there, and 
copy the FP register to the register specified by PDSC$B_SAVE_FP. 


If PDSC$V_KIND = PDSC$K_KIND_FP_STACK, copy the return address 

to the quadword at the RSA$Q_SAVED_RETURN offset in the register save 
area denoted by PDSC$W_RSA_OFFSET, and store the registers specified by 
PDSC$L_IREG_MASK and PDSC$L_FREG_MASK in the register save area 
denoted by PDSC$W_RSA_OFFSET. (This step includes saving the value in 
FP.) 


Execute TRAPB if required (see Section 6.5.3.2 for details). 


3. If PDSC$V_BASE_REG_IS_FP is 0, load register FP with the address of the 
procedure descriptor or the address of a quadword that contains the address 
of the procedure descriptor. 


If PDSC$V_BASE_REG_IS_FP is 1, copy register SP to register FP. 


The ENTRY_LENGTH value in the procedure descriptor provides information 
that is redundant with the setting of a new frame pointer register value. That 
is, the value could be derived by starting at the entry address and scanning the 
instruction stream to find the one that updates FP. The ENTRY_LENGTH value 
included in the procedure descriptor supports the debugger or PCA facility so that 
such a scan is not required. 


Entry Code Example for a Stack Frame Procedure 


Example 3—2 is an entry code example for a stack frame. The example assumes 
that: 


e This is a stack frame procedure 
e Registers R2—4 and F2-3 are saved and restored 
¢ PDSC$W_RSA_OFFSET = 16 


e The procedure has a static exception handler that does not reraise arithmetic 
traps 


e The procedure uses a variable amount of stack 


If the code sequence in Example 3-2 is interrupted by an asynchronous software 
interrupt, SP will have a different value than it did at entry, but the calling 
procedure will still be current. 


After an interrupt, it would not be possible to determine the original value of SP 
by the register frame conventions. If actions by an exception handler result in 

a nonlocal GOTO call to a location in the immediate caller, then it will not be 
possible to restore SP to the correct value in that caller. Therefore, any procedure: 
that contains a label that can be the target of a nonlocal GOTO by immediately 
called procedures must be prepared to reset or otherwise manage the SP at that 
label. 


OpenVMS Alpha Conventions 
3.7 Transfer of Control 


Example 3-2 Entry Code for a Stack Frame Procedure 


LDA SP,-SIZE(SP) ;Allocate space for new stack frame 

STQ R27, (SP) sSet up address of procedure descriptor 

STQ R26,16(SP) *Save return address 

STQ R2,24(SP) *Save first integer register 

STQ R3,32(SP) *Save next integer register 

STQ R4,40(SP) ;Save next integer register 

STQ FP, 48(SP) *Save caller's frame pointer 

STT F2,56(SP) ;Save first floating-point register 

STT F3,64(SP) ;Save last floating-point register 

TRAPB ;Force any pending hardware exceptions to 
. ; be raised 

MOV SP,FP ;Called procedure is now the current procedure 


Entry Code Example for a Register Frame 

Example 3-3 assumes that the called procedure has no static exception handler 
and utilizes no stack storage, PDSC$B_SAVE_RA specifies R26, PDSC$B_SAVE_ 
FP specifies R22, and PDSC$V_BASE_REG_IS_FP is 0: 


Example 3-3 Entry Code for a Register Frame Procedure 


MOV FP,R22 *Save caller's FP. 

MOV R27,FP ;Set FP to address of called procedure’s 
+ descriptor. Called procedure is now the 
; current procedure. 


3.7.5.2 Exit Code Sequence 
When a procedure returns, the exit code must restore the caller’s context, 
synchronize any pending exceptions, and make the caller current by modifying 
the value of FP. The exit code sequence must perform the following steps: 


1. 


If PDSC$V_BASE_REG_IS_FP is 1, then copy FP to SP. 


If PDSC$V_KIND = PDSC$K_KIND_FP_STACK, and this procedure saves or 
restores any registers other than FP and SP, reload those registers from the 
register save area as specified by PDSC$W_RSA_OFFSET. 

If PDSC$V_KIND = PDSC$K_KIND_FP_STACK, load a scratch register with 
the return address from the register save area as specified by PDSC$W_RSA_ 
OFFSET. (If PDSC$V_KIND = PDSC$K_KIND_FP_REGISTER, the return 
address is already in scratch register PDSC$B_SAVE_RA.) 


Execute TRAPB if required (see Section 6.5.3.2 for details). 


If PDSC$V_KIND = PDSC$K_KIND_FP_REGISTER, copy the register 
specified by PDSC$B_SAVE_FP to register FP. 


If PDSC$V_KIND = PDSC$K_KIND_FP_STACK, reload FP from the saved 
FP in the register save area. 


If a function value is not being returned using the stack (PDSC$V_STACK_ 
RETURN_VALUE is 0), then restore SP to the value it had at procedure entry 
by adding the value that was stored in PDSC$L_SIZE to SP. (In some cases, 
the returning procedure will leave SP pointing to a lower stack address than 
it had on entry to the procedure, as specified in Section 3.8.7.) 
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5. Jump to the return address (which is in a scratch register). 


The called routine does not adjust the stack to remove any arguments passed in 
memory. This responsibility falls to the calling routine that may choose to defer 
their removal because of optimizations or other considerations. 


Exit Code Example for a Stack Frame 
Example 3—4 shows the return code sequence for the stack frame. 


Example 3-4 Exit Code Sequence for a Stack Frame 


MOV FP, SP ;Chop the stack back 

LDQ R28,16(FP) ;Get return address 

LDQ R2,24(FP) ;Restore first integer register 

LDQ R3,32(FP) ;Restore next integer register 

LDQ R4,40(FP) ;Restore next integer register 

LDT F2,56(FP) ;Restore first floating-point register 

LDT F3,64(FP) ;Restore last floating-point register 

TRAPB ;Force any pending hardware exceptions to 
>; be raised 

LDQ FP,48(FP) ;Restore caller's frame pointer 

LDA SP, SIZE(SP) ;Restore SP (SIZE is compiled into PDSC$L SIZE) 

RET R31, (R28) ;Return to caller's code 


Interruption of the code sequence in Example 3-4 by an asynchronous software 
interrupt can result in the calling procedure being the current procedure, but 
with SP not yet restored to its value in that procedure. The discussion of that 
situation in entry code sequences applies here as well. 

Exit Code Example for a Register Frame 

Example 3-5 contains the return code sequence for the register frame. 


Example 3-5 Exit Code Sequence for a Register Frame 


MOV R22,FP Restore caller’s FP value 
; Caller is once again the current procedure. 
RET R31, (R26) ;Return to caller’s code 


3.8 Data Passing 


This section defines the OpenVMS Alpha calling standard conventions of passing 
data between procedures in a call chain. An argument item represents one unit 
of data being passed between procedures. 


3.8.1 Argument-Passing Mechanisms 
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This OpenVMS Alpha calling standard defines three classes of argument items 
according to the mechanism used to pass the argument: 


e Immediate value 
e Reference 


¢ Descriptor 
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Argument items are not self-defining; interpretation of each argument item 
depends on agreement between the calling and called procedures. 


This standard does not dictate which passing mechanism must be used by a 
given language compiler. Language semantics and interoperability considerations 
might require different mechanisms in different situations. 


Immediate value 

An immediate value argument item contains the value of the data item. The 
argument item, or the value contained in it, is directly associated with the 
parameter. 


Reference 

A reference argument item contains the address of a data item such as a 
scalar, string, array, record, or procedure. This data item is associated with the 
parameter. 


Descriptor 

A descriptor argument item contains the address of a descriptor, which contains 
structural information about the argument’s type (such as array bounds) and the 
address of a data item. This data item is associated with the parameter. 


3.8.2 Argument List Structure 


The argument list in an OpenVMS Alpha call is an ordered set of zero or more 
argument items, which together comprise a logically contiguous structure known 
as the argument item sequence. An argument item is specified using up to 64 
bits. 


A 64-bit argument item can be used to pass arguments by immediate value, 
by reference, and by descriptor. Any combination of these mechanisms in an 
argument list is permitted. 


Although the argument items form a logically contiguous sequence, they are 

in practice mapped to integer and floating-point registers and to memory in a 
method that can produce a physically discontiguous argument list. Registers 
R16-21 and F16—21 are used to pass the first six items of the argument item 
sequence. Additional argument items must be passed in a memory argument list 
that must be located at 0(SP) at the time of the call. 


Table 3-14 specifies the standard locations in which argument items can be 
passed. 


Table 3-14 Argument Item Locations 
Floating-Point 


Item Integer Register Register Stack 

1 R16 F16 

2 R17 F17 

3 R18 F18 

4 R19 F19 

5 R20 F20 

6 R21 F21 

7-n O(SP) — (n — 7) * 8(SP) 
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The following list summarizes the general requirements that determine the 
location of any specific argument: 


All argument items are passed in the integer registers or on the stack, except 
for argument items that are floating-point data passed by immediate value. 


Floating-point data passed by immediate value is passed in the floating-point 
registers or on the stack. 


Only one location (across an item row in Table 3-14) can be used by any given 
argument item in a list. For example, if argument item 3 is an integer passed 
by value, and argument item 4 is a single-precision floating-point number 
passed by value, then argument item 3 is assigned to R18 and argument item 
4 is assigned to F19. 


A single- or double-precision complex value is treated as two arguments for 
the purpose of argument-item sequence rules. In particular, the real part of a 
complex value might be passed as the sixth argument item in register F21, in 
which case the imaginary part is then passed as the seventh argument item 
in memory. 


The argument list that includes both the in-memory portion and the portion 
passed in registers can be read from and written to by the called procedure. 
Therefore, the calling procedure must not make any assumptions about the 
validity of any part of the argument list after the completion of a call. 


3.8.3 Argument Lists and High-Level Languages 


High-level language functional notations for procedure call arguments are 
mapped into argument item sequences according to the following requirements: 


Arguments are mapped from left to right to increasing offsets in the argument 
item sequence. R16 or F16 is allocated to the first argument, and the last 
quadword of the memory argument list (if any) is allocated to the last 
argument. 


Each source language argument corresponds to a single Alpha calling 
standard argument item. 


Each argument item consists of 64 bits. 


A null or omitted argument—for example, CALL SUB(A,,B)—is represented 
by an argument item containing the value 0. 


Arguments passed by immediate value cannot be omitted unless a default 
value is supplied by the language. (This is to enable called procedures 

to distinguish an omitted immediate argument from an immediate value 
argument with the value 0.) 


Trailing null or omitted arguments—for example, CALL SUB(A,,)—are passed 


_by the same rules as for embedded null or omitted arguments. 


3.8.4 Unused Bits in Passed Data 


Whenever data is passed by value between two procedures in registers (for the 
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first six input arguments and return values), or in memory (for arguments after 


the first six), the bits not used by the data are sign extended or zero extended as 
appropriate. 
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Table 3-15 lists and defines the various data-type requirements for size and their 
extensions to set or clear unused bits. 


Table 3-15 Data Types and the Unused Bits in Passed Data 


Register Memory 

Type Data Size Extension Extension 
Data Type Designator (bytes) Type Type 
Byte logical BU 1 Zero64 Zero64 
Word logical WU 2 Zero64 Zero64 
Longword logical ; LU 4 Sign64 Sign64 
Quadword logical QU 8 Data64 Data64 
Byte integer B 1 Sign64 Sign64 
Word integer W 2 Sign64 Sign64 
Longword integer L 4 Sign64 Sign64 
Quadword integer Q 8 Data64 Data64 
F_floating F 4 Hard Data32 
D_floating D 8 Hard Data64 
G_floating G 8 Hard Data64 
F_floating complex FC 2%4 2«Hard 2%Data32 
D_floating complex DC 2%«8 2*Hard 2*Data64 
G_floating complex GC 2%8 2«Hard 2% Data64 
S_floating FS 4 Hard Data32 
T_floating FT 8 Hard Data64 
X_floating FX 16 N/A N/A 
S_floating complex FSC 2%4 _ 24aHard 24Data32 
T_floating complex FTC 248 2«Hard 2%Data64 
X_floating complex . FXC 2 16 N/A N/A 
Small structures of 8 bytes or less N/A <8 Nostd Nostd 
Small arrays of 8 bytes or less N/A <8 Nostd Nostd 
32-bit address N/A 4 Sign64 Sign64 
64-bit address N/A 8 Data64 Data64 


The following are the defined meanings for the extension type symbols used in 
Table 3-15: 
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Sign Extension 


Type Defined Function 

Sign64 Sign-extended to 64 bits. 

Zero64 Zero-extended to 64 bits. 

Data32 Data is 32 bits. The state of bits <63:32> is unpredictable. 

2+*Data32 Two single-precision parts of the complex value are stored in memory 
as independent floating-point values (each handled as Data32). 

Data64 Data is 64 bits. 

2«Data64 Two double-precision parts of the complex value are stored in memory 
as independent floating-point values (each handled as Data64). 

Hard Passed in the layout defined by the hardware SRM. 

2xHard Two floating-point parts of the complex value are stored in a pair of 


registers as independent floating-point values (each handled as Hard). 


Nostd State of all high-order bits not occupied by the data is unpredictable 
across a call or return. 


Because of the varied rules for sign extension of data when passed as arguments, 
both calling and called routines must agree on the data type of each argument. 
No implicit data-type conversions can be assumed between the calling procedure 
and the called procedure. 


3.8.5 Sending Data 


This section defines the OpenVMS Alpha calling standard requirements for 
mechanisms to send data and the order of argument evaluation. 


3.8.5.1 Sending Mechanism 


As previously defined, the argument-passing mechanisms allowed are immediate 
value, reference, and descriptor. Requirements for using these mechanisms 
follow: 


¢ By immediate value. An argument can be passed by immediate value only 
if the argument is one of the following: 


— One of the noncomplex scalar data types with a size known (at compile 
time) to be < 64 bits 


— Arecord with a known size (at compile time) 


— Aset, implemented as a bit vector, with a size known (at compile time) to 
be < 64 bits 


No form of string, array, or complex data type can be passed by immediate 
value. 


A standard immediate argument item must fill 64 bits. This means that 
unused high-order bits of all data types (including records) must be zero 
extended or sign extended, depending on the data type, to fill all unused bits 
(as specified in Table 3-15). 


Large immediate arguments — Record values that are larger than 64 bits 
can be passed by immediate value as follows: 


— Allocate as many fully occupied argument item positions to the argument 
value that are needed to represent the argument. 


—- A final partially occupied argument item position, if any, must be zero 
extended to fill the entire item position. 
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— An argument item in a register is passed in one of the integer registers 
(never in a floating-point register). 

Note that in a large immediate argument, the argument count reflects 

the number of argument positions used rather than the number of actual 

arguments. 

Nonstandard immediate arguments — Nonrecord argument values that 

are larger than 64 bits can be passed by immediate value using nonstandard 

conventions, typically using a method similar to that used for records. For 

example, a 64-bit complex floating-point argument can be passed by value in 

two floating-point registers. A 26-byte string can be passed by value in four 

integer registers. 


¢ By reference. Nonparametric arguments (arguments for which associated 
information such as string size and array bounds are not required) can be 
passed by reference in a standard call. 


e By descriptor. Parametric arguments (arguments for which associated 
information such as string size and array bounds must be passed to the 
caller) are passed by a single descriptor in a standard call. 


Note that extended floating values are not passed using the immediate value 
mechanism; rather, they are passed using the by reference mechanism. (However, 
when by value semantics is required, it may be necessary to make a copy of the 
actual parameter and pass a reference to that copy in order to avoid improper 
alias effects.) 


Also note that when a record is passed by immediate value, the component 
types are not material to how the argument is aligned; the record will always be 
quadword aligned. | 


3.8.5.2 Order of Argument Evaluation 
Since most high-level languages do not specify the order of evaluation (with 
respect to side effects) of arguments, those language processors can evaluate 
arguments in any convenient order. The choice of argument evaluation order and 
code generation strategy is constrained only by the definition of the particular 
language. Programs should not depend on the order of evaluation of arguments. 


3.8.6 Receiving Data 


When it cannot be determined at compile time whether a given in-register 
argument item is passed in a floating-point register or an integer register, the 
argument information register can be interpreted at run time to establish where 
the argument was passed. (See Section 3.7.1 for details.) 


3.8.7 Returning Data 


A standard function must return its function value by one of the following 
mechanisms: 


¢ Immediate value 
e Reference 
e Descriptor 


These mechanisms are the only standard means available for returning function 
values, and they support the important language-independent data types. 
Functions that return values by any mechanism other than those specified here 
are nonstandard, language-specific functions. 
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3.8.7.1 Function Value Return by Immediate Value 


This standard defines the following two types of function returns by immediate 
value: 


¢ Nonfloating function value return 
e Floating function value return 


Nonfloating Function Value Return by Immediate Value 

A function value is returned by immediate value in register RO only if the type of 
function value is one of the following: 

¢ Nonfloating-point scalar data type with size known to be < 64 bits 

¢ Record with size known to be < 64 bits 

e Set, implemented as a bit vector, with size known to be < 64 bits 


No form of string or array can be returned by immediate value, and two separate 
32-bit entities cannot be combined and returned in RO. 


A function value of less than 64 bits returned in RO must be zero extended or sign 
extended as appropriate, depending on the data type (see Table 3-15), to a full 
quadword. 


Floating Function Value Return by Immediate Value 
A function value is returned by immediate value in register FO only if it is a 
noncomplex single- or double-precision floating-point value (F, D, G, S, or T). 


A function value is returned by immediate value in registers FO and F1 only if it 
is a complex single or double-precision floating-point value (complex F, D, G, 8S, or 
T). 


3.8.7.2 Function Value Return by Reference 
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A function value is returned by reference only if the function value satisfies both 
of the following criteria: 


¢ Its size is known to both the calling procedure and the called procedure, but 
the value cannot be returned by immediate value. (Because the function 
value requires more than 64 bits, the data type is a string or an array type.) 


¢ It can be returned in a contiguous region of storage. 


The actual-argument list and the formal-argument list are shifted to the right 
by one argument item. The new, first argument item is reserved for the function 
value. This hidden first argument is included in the count and register usage 
information that is passed in the argument information register (see Section 3.7.1 
for details). 


The calling procedure must provide the required contiguous storage and pass the 
address of the storage as the first argument. This address must specify storage 
naturally aligned according to the data type of the function value. 


The called function must write the function value to the storage described by the 
first argument. 
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3.8.7.3 Function Value Return by Descriptor 
A function value is returned by descriptor only if the function value satisfies all of 
the following criteria: 


e It cannot be returned by immediate value. (Because the function value 
requires more than 64 bits, the data type is a string or an array type, and so 
on.) 


e Its size is not known to either the calling procedure or the called procedure. 
e It can be returned in a contiguous region of storage. 


Noncontiguous function values are language specific and cannot be returned as a 
standard-conforming return value. 


Records, noncontiguous arrays, and arrays with more than one dimension cannot 
be returned by descriptor in a standard call. 


Both 32-bit and 64-bit descriptor forms can be used for function values returned 
by descriptor. See Chapter 5 for details of the descriptor forms. 


The use of descriptors for function value return divides into three major cases 
with return values involving: 


e Dynamic text—Heap-managed strings of arbitrary and dynamically 
changeable length 


e Return objects created by the calling routine—Function values that are to be 
returned in an object allocated by and having attributes (bounds, lengths, and 
so on) specified by the calling routine 


¢ Return objects created by the called routine—Function values that are. 
returned in an object allocated by and having attributes (bounds, lengths, 
and so on) specified by the called routine 


For correct results to be obtained from this type of function return, the calling 
and called routines must agree by prior arrangement which of these three major 
cases applies, and whether 64-bit descriptor forms may be used. 


The following paragraphs describe the specialized requirements for each major 
case: 


Dynamic Text 

For dynamic text return by descriptor, the calling routine passes a valid 
(completely initialized) dynamic string descriptor (DSC$B_CLASS = DSC$K_ 
CLASS_D). The called routine must assign a value to the variable represented by 
this descriptor using the same rules that apply to a dynamic text descriptor used 
as an ordinary parameter. 


Return Object Created by Calling Routine 


For a return object created by the calling routine, the calling routine passes a 
descriptor in which all fields are completely loaded. 


The called routine must supply a return value that satisfies that description. In 
particular, the called routine must truncate or pad the returned value to satisfy 
the requirements of the descriptor according to the semantics of the language in 
which the called routine is written. 


The calling and called routines must agree by prior arrangement on the DSC$B_ 
CLASS and DSC$B_DTYPE of descriptor to be used. 
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Return Object Created by Called Routine 

For a return object created by the called routine, the calling and called routines 
must agree by prior arrangement on the DSC$B_CLASS and DSC$B_DTYPE of 
descriptor to be used. The calling routine passes a descriptor in which: 


e DSC$A_POINTER field is set to zero. 
¢ DSC$B_CLASS field is loaded. 
¢ DSC$B_DTYPE field is loaded. 


¢ DSC$B_DIMCT field is loaded and the DSC$B_AFLAGS field is set to zero if 
the descriptor is an array descriptor. 


e All other fields are unpredictable. 


If the passed descriptor is an array descriptor, it must contain space for bounds 
information to be returned even though the DSC$B_AFLAGS field is set to zero. 


The called routine must return the function value using stack return conventions 
and load the DSC$A_POINTER field to point to the returned data. Other 
descriptor information, such as origin, bounds (if supplied), and DSC$B_AFLAGS 
fields must be filled in appropriately to correspond to the returned data. 


An important implication of a call that uses this kind of value return is that 

the stack pointer normally is not restored to its value prior to the call as part 

of the return from the called procedure. The returned value typically (but not 
necessarily) is left by the called routine somewhere on the stack. For that reason, 
this mechanism is sometimes known as the stack return mechanism. 


However, this type of return does not imply that the actual storage used by the 
called routine to hold the returned value must be at the address pointed to by 
the stack pointer; it need not even be on the stack. It could be in some read-only, 
static memory. (This latter case might arise when the returned value is constant 
or is obtained from some constant structure.) For this reason, the calling routine 
must not assume that the data described by the return descriptor is writable. 


3.9 Static Data 


This section describes the standard static data requirements that define the 
Alpha alignment of data structures, record formats, and record layout. These 
conventions help to ensure proper data compatibility with all OpenVMS Alpha 
and VAX languages. 


3.9.1 Alignment 
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In the Alpha environment, memory references to data that is not naturally 
aligned can result in alignment faults, which can severely degrade the 
performance of all procedures that reference the unaligned data. 


To avoid such performance degradation, all data values on Alpha systems should 
be naturally aligned. Table 3-16 contains information on data alignment. top 


OpenVMS Alpha Conventions 
3.9 Static Data 


Table 3-16 Data Alignment Addresses 


Data Type Alignment Starting Position 

8-bit character string Byte boundary 

16-bit integer Address that is a multiple of 2 (word alignment) 
32-bit integer Address that is a multiple of 4 (longword alignment) 
64-bit integer Address that is a multiple of 8 (quadword alignment) 
F_floating Address that is a multiple of 4 (longword) 

F floating complex 

D_floating Address that is a multiple of 8 (quadword) 
D_floating complex 

G_floating Address that is a multiple of 8 (quadword) 
G_floating complex 

S_floating Address that is a multiple of 4 (ongword alignment) 
S_floating complex 

T_floating © Address that is a multiple of 8 (quadword) 
T_floating complex 

X_floating Address that is a multiple of 16 (octaword) 


X_floating complex 


For aggregates such as strings, arrays, and records, the data type to be considered 
for purposes of alignment is not the aggregate itself, but rather the elements of 
which the aggregate is composed. The alignment requirement of an aggregate 

is that all elements of the aggregate be naturally aligned. For example, varying 
8-bit character strings must start at addresses that are a multiple of at least 2 
(word alignment) because of the 16-bit count at the beginning of the string; 32-bit 
integer arrays start at a longword boundary, irrespective of the extent of the 
array. 


The rules for passing a record in an argument that is passed by immediate 
value (see Section 3.8.5.1) always provide quadword alignment of the record 
value independent of the normal alignment requirement of the record. If deemed 
appropriate by an implementation, normal alignment can be established within 
the called procedure by making a copy of the record argument at a suitably 
aligned location. 


3.9.2 Record Layout Conventions 


The OpenVMS Alpha calling standard rules for record layout are designed 

to provide good run-time performance on all implementations of the Alpha 
architecture and to provide the required level of compatibility with conventional 
VAX operating environments. 


Therefore, this standard defines two record layout conventions: 


¢ Those optimized for optimal access characteristics (referred to as aligned 
record layouts) 


e¢ Those compatible with conventions that are traditionally used by VAX 
languages (referred to as VAX compatible record layouts) 
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Note 


Although compiler implementers must make appropriate business 
decisions, Digital strongly recommends that all Alpha high-level language 
compilers should support both record layouts. 


Only these two record layouts may be used across standard interfaces or 
between languages. Languages can support other language-specific record 
layout conventions, but such layouts are nonstandard. 


The aligned record layout conventions should be used unless interchange is 
required with conventional VAX applications that use the VAX VMS or OpenVMS 
VAX compatible record layouts. 

3.9.2.1 Aligned Record Layout 
The aligned record layout conventions ensure that: 


All components of a record or subrecord are naturally aligned. 


Layout and alignment of record elements and subrecords are independent of 
any record or subrecord in which they are embedded. 


Layout and alignment of a subrecord is the same as if it were a top-level 
record. 


Declaration in high-level languages of standard records for interlanguage use 
is straightforward and obvious, and meets the requirements for source level 
compatibility between Alpha and VAX languages. 


The aligned record layout is defined by the following conventions: 
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The components of a record must be laid out in memory corresponding to the 
lexical order of their appearance in the high-level language declaration of the 
record. 


The first bit of a record or subrecord must be directly addressable (byte 
aligned). 


Records and subrecords must be aligned according to the largest natural 
alignment requirements of the contained elements and subrecords. 


Bit fields (packed subranges of integers) are characterized by an underlying 
integer type that is a byte, word, longword, or quadword in size together with 
an allocation size in bits. A bit field is allocated at the next available bit 
boundary, provided that the resulting allocation does not cross an alignment 
boundary of the underlying type. Otherwise, the field is allocated at the 
next byte boundary that is aligned as required for the underlying type. (In 
the later case, the space skipped over is left permanently not allocated.) In 
addition, if necessary, the alignment of the record as a whole is increased to 
that of the underlying integer type. 


Unaligned bit strings, unaligned bit arrays, and elements of unaligned bit 
arrays must start at the next available bit in the record. No fill is ever 
supplied preceding an unaligned bit string, unaligned bit array, or unaligned 
bit array element. 


All other components of a record must start at the next available naturally 
aligned address for the data type. 
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The length of a record must be a multiple of its alignment. (This includes the 
case when a record is a component of another record.) 


Strings and arrays must be aligned according to the natural alignment 
requirements of the data type of which the string or array is composed. 


The length of an array element is a multiple of its alignment, even if this 
leaves unused space at its end. The length of the whole array is the sum of 
the lengths of its elements. 


3.9.2.2 OpenVMS VAX Compatible Record Layout 


The OpenVMS VAX compatible record layout is defined by the following 
conventions: 


The components of a record must be laid out in memory corresponding to the 
lexical order of their appearance in the high-level language declaration of the 
record. 


Unaligned bit strings, unaligned bit arrays, and elements of unaligned bit 
arrays must start at the next available bit in the record. No fill is ever 
supplied preceding an unaligned bit string, unaligned bit array, or unaligned 
bit array element. 


All other components of a record must start at the next available byte in 
the record. Any unused bits following the last-used bit in the last-used byte 
of each component must be filled out to the next byte boundary so that any 
following data starts on a byte boundary. 


Subrecords must be aligned according to the largest alignment of the 
contained elements and subrecords. A subrecord always starts at the 
next available byte unless it consists entirely of unaligned bit data and 
it immediately follows an unaligned bit string, unaligned bit array, or a 
subrecord consisting entirely of unaligned bit data. 


Records must be aligned on byte boundaries. 


3.10 Multithreaded Execution Environments 


This section defines the conventions to support the execution of multiple threads 
in a multilanguage Alpha environment. Specifically defined is how compiled code 
must perform stack limit checking. While this standard is compatible with a 
multithreaded execution environment, the detailed mechanisms, data structures, 
and procedures that support this capability are not specified in this manual. 


For a multithread environment, the following characteristics are assumed: 


There can be one or more threads executing within a single process. 
The state of a thread is represented in a thread environment block (TEB). 


The TEB of a thread contains information that determines a stack limit 
below which the stack pointer must not be decremented by the executing code 
(except for code that implements the multithread mechanism itself). 


Exception handling is fully reentrant and multithreaded. 


The correct way to terminate a thread is by returning from the initial 
procedure in which the thread begins execution, or by a call to SYS$GOTO_ 
UNWIND, specifying a null target environment or some other procedure that 
includes this effect. Note that correct thread termination involves unwind 
processing for all of the active frames of the thread. 
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3.10.1 Stack Limit Checking 


A program that is otherwise correct can fail because of stack overflow. Stack 
overflow occurs when extension of the stack (by decrementing the stack pointer, 
SP) allocates addresses not currently reserved for the current thread’s stack. 


Detection of a stack overflow situation is necessary because a thread, attempting 
to write into stack storage, could modify data allocated in that memory for some 
other purpose. This would most likely produce unpredictable and undesirable 
results or irreproducible application failures. 


The requirements for procedures that can execute in a multithread environment 
include checking for stack overflow. This section defines the conventions for stack 
limit checking in a multithreaded program environment. 


In the following sections, the term new stack region refers to the region of the 
stack from the old value of SP — 1 to the new value of the SP. 


3.10.1.1 Stack Guard Region 


In a multithread environment, the memory beyond the limit of each thread’s 
stack is protected by contiguous guard pages, which form the stack’s guard 
region. 


3.10.1.2 Stack Reserve Region 


In some cases, it is desirable to maintain a stack reserve region, which is a 
minimum-sized region that is immediately above a thread’s guard region. A 
reserve region may be desirable to ensure that exceptions or asynchronous system 
traps (ASTs) have stack space to execute on a thread’s stack, or to ensure that 
the exception dispatcher and any exception handler that it might call have stack 
space to execute after detection of an invalid attempt to extend the stack. 


This standard does not require a reserve region. 


3.10.1.3 Methods for Stack Limit Checking 


Since accessible memory may be available at addresses lower than those occupied 
by the guard region, compilers must generate code that never extends the stack 
past the guard pages into accessible memory that is not allocated to the thread’s 
stack. 


A general strategy is to access each page of memory down to and possibly 
including the page corresponding to the intended new value for the SP. If the 
stack is to be extended by an amount larger than the size of a memory page, then 
a series of accesses is required that works from higher to lower addressed pages. 
If any access results in a memory access violation, then the code has made an 
invalid attempt to extend the stack of the current thread. 


Note 


An access can be performed by using either a load or a store operation; 
however, be sure to use an instruction that is guaranteed to make an 
access to memory. For example, do not use an LDQ R31,* instruction, 
because the Alpha architecture does not allow any memory access, even a 
read access, whose result is discarded because of the R31 destination. 


This standard defines two methods for stack limit checking: implicit and explicit. 
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Implicit Stack Limit Checking 
Two mutually exclusive strategies for implicit stack limit checking are: 


¢ Ifthe lowest addressed byte of the new stack region is guaranteed to be 
accessed prior to any further stack extension, then the stack can be extended 
by an increment that is equal in size to the guard region (without any further 
accesses). 


e Ifsome byte (not necessarily the lowest) of the new stack region is guaranteed 
to be accessed prior to any further stack extension, then the stack can be 
extended by an increment that is equal in size to one-half the guard region 
(without any further accesses). 


The stack frame format (see Section 3.4.3) and entry code rules (see Section 3.7.5) 
generally do not ensure access to the lowest address of a new stack region without 
introducing an extra access solely for that purpose. Consequently, this standard 
uses the second strategy. While the amount of implicit stack extension that can 
be achieved is smaller, the check is achieved at no additional cost. 


This standard requires that the minimum guard region size is 8192 bytes, the size 
of the smallest memory protection granularity allowed by the Alpha architecture. 


Therefore, if the stack is being extended by an amount less than or equal to 4096 
and a reserve region is not required, then explicit stack limit checking is not 
required. 


However, because asynchronous interrupts and calls to other procedures may also 
cause stack extension without explicit stack limit checking, stack extension with 
implicit limit checking must adhere to a strict set of conventions: 


1. Explicit stack limit checking must be performed unless the amount by which 
the SP is decremented is known to be less than or equal to 4096 and a reserve 
region is not required. 


2. Some byte in the new stack region must be accessed before the SP can be 
decremented for a subsequent stack extension. 


This access can be performed either before or after the SP is decremented for 
this stack extension, but it must be done before the SP can be decremented 
again. 


3. No standard procedure call can be made before some byte in the new stack 
region is accessed. 


4. The system exception dispatcher ensures that the lowest addressed byte in 
the new stack region is accessed if any kind of asynchronous interrupt occurs 
after the SP is decremented, but before the access in the new stack region 
occurs. 


These conventions ensure that the stack pointer is not decremented so that 

it points to accessible storage beyond the stack limit without this error being 
detected (either by the guard region being accessed by the thread or by an explicit 
stack limit check failure). 


As a matter of practice, the system can provide multiple guard pages in the 
guard region. When a stack overflow is detected as a result of access to the guard 
region, one or more guard pages can be unprotected for use by the exception- 
handling facility, and one or more guard pages can remain protected to provide 
implicit stack limit checking during exception processing. However, the size of 
the guard region and the number of guard pages is system defined and is not 
defined by this standard. 
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Explicit Stack Limit Checking 

If the stack is being extended by an amount of unknown size or by a known size 
greater than the maximum implicit check size (4096), then a code sequence that 
follows the rules for implicit stack limit checking can be executed in a loop to 
access the new stack region incrementally in segments lesser than or equal to 
the minimum page size (8192 bytes). At least one access must occur in each such 
segment. The first access must occur between SP and SP — 4096 because, in the 
absence of more specific information, the previous guaranteed access relative to 
the current stack pointer may be as much as 4096 bytes greater than the current 
stack pointer address. The last access must be within 4096 bytes of the intended 
new value of the stack pointer. These accesses must occur in order, starting 
with the highest addressed segment and working toward the lowest addressed 
segment. 


Note 


A simple algorithm that is consistent with this requirement (but achieves 
up to twice the minimum number of accesses) is to perform a sequence 
of accesses in a loop starting with the previous value of SP, decrementing 
by the minimum no-check extension size (4096) to, but not including, the 
first value that is less than the new value for the stack pointer. 


The stack must not be extended incrementally in procedure prologues. A 
procedure prologue that needs to extend the stack by an amount of unknown 
size or known size greater than the minimum implicit check size must test new 
stack segments as just described in a loop that does not modify SP, and then 
update the stack with one instruction that copies the new stack pointer value into 
the SP. 


Note 


An explicit stack limit check can be performed either by inline code that 
is part of a prologue or by a run-time support routine that is tailored to 
be called from a procedure prologue. . 


Stack Reserve Region Checking 


The size of the reserve region must be included in the increment size used for. 
stack limit checks, after which it is not included in the amount by which the 
stack is actually extended. (Depending on the size of the reserve region, this 
may partially or even completely eliminate the ability to use implicit stack limit 
checking.) 


3.10.1.4 Stack Overflow Handling 
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If a stack overflow is detected, one of the following results: 
e Exception SS$_ACCVIO may be raised. 


e The system may transparently extend the thread’s stack, reset the TEB stack 
limit value appropriately, and continue execution of the thread. 


Note that if a transparent stack extension is performed, a stack overflow that 
occurs in a called procedure might cause the stack to be extended. Therefore, the 
TEB stack limit value must be considered volatile and potentially modified by 
external procedure calls and by handling of exceptions. 
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This chapter defines the argument-passing data types that are used to call a 
procedure for both VAX and Alpha environments. All features defined here apply 
to both OpenVMS VAX and OpenVMS Alpha systems unless otherwise noted. 


Each data type implemented for a high-level language uses one of the following 
classes of VAX data types for procedure parameters and elements of file records: 


e Atomic 
e String 
e Miscellaneous 


When existing data types fail to satisfy the semantics of a language, new data 
types, including certain language-specific ones, are added to this standard. These 
data types can generally be passed by immediate value (if 32 bits or less), by 
reference, or by descriptor. 


Each data type code presented in this chapter indicates a unique data format. 
Use these encodings whenever you need to identify data types to achieve greater 
commonality across user software. 


The encoding given in Sections 4.1 and 4.2 can help you to identify data types, 
such as in a descriptor. However, in addition to their use in descriptors, these 
data type codes are also useful for identifying VAX and Alpha data types in areas 
outside the scope of the calling standard. Therefore, each data-type code indicates 
a unique data format independent of its use in descriptors. 


Some data types are composed of a recordlike structure consisting of two or more 
elementary data types. For example, the F_floating complex (FC) data type is 
made up of two F_floating data types, and the varying character string (VT) data 
type is made up of a word (unsigned, WU). data type followed by a character 
string (T) data type. 


Unless stated otherwise, all data types in this standard represent signed 
quantities. The unsigned quantities do not allocate space for the sign; all bit or 
character positions are used for significant data. 

4.1 Atomic Data Types 


Table 4—1 shows how atomic data types are defined and encoded for VAX and 
Alpha environments. 
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Table 4—1 Atomic Data Types 
Symbol Code Name/Description 


DSC$K_DTYPE_Z 0 Unspecified 


The calling program has specified no data type. The 
default argument for the called procedure should be 
the correct type. 


DSC$K_DTYPE_BU 2 Byte (unsigned) 

8-bit unsigned quantity. 
DSC$K_DTYPE_WU 3 Word (unsigned) 

16-bit unsigned quantity. 
DSC$K_DTYPE_LU 4 Longword (unsigned) 

32-bit unsigned quantity. 
DSC$K_DTYPE_QU 5 Quadword (unsigned) 

64-bit unsigned quantity. 
DSC$K_DTYPE_OU 25 Octaword (unsigned) 

128-bit unsigned quantity. 
DSC$K_DTYPE_B 6 Byte integer (signed) 

8-bit signed two’s complement integer. 
DSC$K_DTYPE_W | Word integer (signed) 

16-bit signed two’s complement integer. 
DSC$K_DTYPE_L 8 Longword integer (signed) 

, 32-bit signed two’s complement integer. 

DSC$K_DTYPE_Q 9 Quadword integer (signed) 

64-bit signed two’s complement integer. 
DSC$K_DTYPE_O 26 Octaword integer (signed) 

128-bit signed two’s complement integer. 
DSC$K_DTYPE_F 10 F_floating 


32-bit F_floating quantity representing a single- 
precision number. 
DSC$K_DTYPE_D! 11 D_floating 
64-bit D_floating quantity representing a double- 
. precision number. 
DSC$K_DTYPE_G 27 G_floating 
64-bit G_floating quantity representing a double- 
precision number. 
+DSC$K_DTYPE_H? 28 H_floating 


128-bit H_floating quantity representing a quadruple- 
precision number. 


1While the calling standard supports the manipulation of D_floating and D_floating complex data, 
compiled code support will invoke conversion from D_floating to G_floating as needed for Alpha 
arithmetic operations, and conversion of G_floating intermediate results back to D_floating when 
needed for stores to memory or parameter passing. This allows D_floating data to be used in Alpha 
arithmetic operations without required source changes but with results limited to G_floating precision. 


2H floating data is not supported for general use on OpenVMS Alpha systems. However, 
conversion routines are supplied to allow users to convert existing H_floating data to other storage 
representations. 


{VAX specific. 


(continued on next page) 
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Table 4—1 (Cont.) Atomic Data Types 


Symbol 
DSC$K_DTYPE_FC 


DSC$K_DTYPE_DC 


DSC$K_DTYPE_GC 


+DSC$K_DTYPE_HC? 


tDSC$K_DTYPE_FS 


+DSC$K_DTYPE_FT 


+DSC$K_DTYPE_FSC 


+DSC$K_DTYPE_FTC 


+DSC$K_DTYPE_FX 


tDSC$K_DTYPE_FXC 


Code 
12 


13 


29 


30 


52 


53 


54 


55 


57 


58 


Name/Description 


F_floating complex 


Ordered pair of F_floating quantities representing 
a single-precision complex number. The lower 
addressed quantity is the real part; the higher 
addressed quantity is the imaginary part. 


D_floating complex 


Ordered pair of D_floating quantities representing 
a double-precision complex number. The lower 
addressed quantity is the real part; the higher 
addressed quantity is the imaginary part. 


G_floating complex 


Ordered pair of G_floating quantities representing 
a double-precision complex number. The lower 
addressed quantity is the real part; the higher 
addressed quantity is the imaginary part. 


H_floating complex 


Ordered pair of H_floating quantities representing 
a quadruple-precision complex number. The lower 
addressed quantity is the real part; the higher 
addressed quantity is the imaginary part. 


S_floating 


32-bit IEEE S_floating quantity representing a 
single-precision number. 


T_floating 

64-bit IEEE T_floating quantity representing a 
double-precision number. 

S_floating complex 


Ordered pair of S_floating quantities representing 
a single-precision complex number. The lower 
addressed quantity is the real part; the higher 
addressed quantity is the imaginary part. 


T floating complex 


Ordered pair of T_floating quantities representing 
a single-precision complex number. The lower 
addressed quantity is the real part; the higher 
addressed quantity is the imaginary part. 


X_floating 


128-bit IEEE X_floating quantity representing an 
extended-precision number. 


X_floating complex 


Ordered pair of X_floating quantities representing an 
extended-precision complex number. The lower 
addressed quantity is the real part; the higher 
addressed quantity is the imaginary part. 


2H floating data is not supported for general use on OpenVMS Alpha systems. However, 
conversion routines are supplied to allow users to convert existing H_floating data to other storage 


representations. 
TVAX specific. 
tAlpha specific. 
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4.2 String Data Types 


String data types are ordinarily described by a string descriptor. Table 4-2 
shows how the string data types are defined and encoded for OpenVMS VAX and 
OpenVMS Alpha environments. 


Table 4—2 String Data Types 
Symbol Code Name/Description 


DSC$K_DTYPE_T 14 Character string 


A single 8-bit character (atomic data type) or a 
sequence of 0 to 2!° — 1 eight-bit characters (string 
data type). 


DSC$K_DTYPE_VT 37 Varying character string 


A 16-bit unsigned count of the current number of 
8-bit characters in the following string, followed 

by a string of 0 to 2’° — 1 eight-bit characters (see 
Section 4.5 for details). When this data type is used 
with descriptors, it can only be used with the varying 
string and varying string array descriptors, because 
the length field is interpreted differently from the 
other 8-bit string data types. (See Sections 4.5, 5.8, 
and 5.9 for further discussion.) 


DSC$K_DTYPE_NU 15 Numeric string, unsigned 
DSC$K_DTYPE_NL 16 Numeric string, left separate sign 
DSC$K_DTYPE_NLO 17 Numeric string, left overpunched sign 
DSC$K_DTYPE_NR 18 Numeric string, right separate sign 
DSC$K_DTYPE_NRO 19 Numeric string, right overpunched sign 
DSC$K_DTYPE_NZ 20 Numeric string, zoned sign 
DSC$K_DTYPE_P 21 Packed-decimal string 
DSC$K_DTYPE_V 1 Aligned bit string 


A string of 0 to 2!° — 1 contiguous bits. The first bit 
is bit <0> of the first byte, and the last bit is any bit 
in the last byte. Remaining bits in the last byte must 
be zero on read and are cleared on write. Unlike the 
unaligned bit string (VU) data type, when the aligned 
bit string (V) data type is used in array descriptors, 
the ARSIZE field is in units of bytes, not bits, because 
allocation is a multiple of 8 bits. 


DSC$K_DTYPE_VU 34 Unaligned bit string 


The data is 0 to 2!® — 1 contiguous bits located 
arbitrarily with respect to byte boundaries. See also 
aligned bit string (V) data type. Because additional 
information is required to specify the bit position of 
the first bit, this data type can be used only with 
the unaligned bit string and unaligned bit array 
descriptors (see Sections 5.10 and 5.11). 


4.3 Miscellaneous Data Types 


Table 4—3 shows how miscellaneous data types are defined and encoded for 
OpenVMS VAX and OpenVMS Alpha environments. 
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Table 4-3 Miscellaneous Data Types 


Symbol 


+DSC$K_DTYPE_ZI 
+DSC$K_DTYPE_ZEM 
DSC$K_DTYPE_DSC 


+DSC$K_DTYPE_BPV 


DSC$K_DTYPE_BLV 


DSC$K_DTYPE_ADT 


VAX specific. 


Code 


22 
23 
24 


32 


33 


35 


4.4 Reserved Data-Type Codes 


All codes from 0 through 191 not otherwise defined in this standard are reserved 
to Digital. Codes 192 through 255 are reserved to Digital’s Computer Special 
Systems Group and for customers for their own use. 


Name/Description 


Sequence of instructions 
Procedure entry mask 
Descriptor 


This data type allows a descriptor to be a data type; 
thus, levels of descriptors are allowed. 


Bound procedure value (for VAX environment only) 


A two-longword entity in which the first longword 
contains the address of a procedure entry mask and 
the second longword is the environment value. The 
environment value is determined in a language- 
specific manner when the original bound procedure 
value is generated. When the bound procedure is 
called, the calling program loads the second longword 
into R1. When the environment value is not needed, 
this data type can be passed using the immediate 
value mechanism. In this case, the argument list 
entry contains the address of the procedure entry 
mask and the second longword is omitted. 


Bound label value 


A two-longword entity in which the first longword 
contains the address of an instruction and the second 
longword is the language-specific environment value. 
The environment value is determined in a language- 
specific manner when the original bound label value 
is generated. 


Absolute date and time 


A 64-bit unsigned, scaled, binary integer representing 
a date and time in 100-nanosecond units offset 

from the OpenVMS operating system base date and 
time, which is 00:00 o’clock, November 17, 1858 (the 
Smithsonian base date and time for astronomical 
calendars). The value zero indicates that the date 
and time have not been specified, so a default value 
or distinctive print format can be used. 


Note that the ADT data type is the same as the 
OpenVMS date format for positive values only. 


Table 4-4 lists the data types and codes that are obsolete or reserved to Digital. 
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Table 4-4 Reserved Data Types 


Symbol Code Purpose 
DSC$K_DTYPE_CIT 31 Reserved to COBOL (intermediate temporary) 
DSC$K_DTYPE_CIT2 64 Reserved to COBOL (intermediate temporary 
alternative 2) 
DSC$K_DTYPE_TF 40 Reserved to DEBUG (Boolean true/false) 
DSC$K_DTYPE_SV 41 Reserved to DEBUG (signed bit-field, aligned) 
DSC$K_DTYPE_SVU 42 Reserved to DEBUG (signed bit-field, unaligned) 
DSC$K_DTYPE_FIXED 48 Reserved to DEBUG (fixed binary—fixed pom in Ada 
and fixed binary in PL/I) 
DSC$K_DTYPE_TASK 44 Reserved to DEBUG (task type in Ada) 
DSC$K_DTYPE_AC 45 Reserved to DEBUG (ASCIC text) 
DSC$K_DTYPE_AZ 46 Reserved to DEBUG (ASCIZ text) 
DSC$K_DTYPE_M68_S 47 aoe to DEBUG (Motorola 68881 single precision, 
-bi 
DSC$K_DTYPE_M68_D 48 Reserved to DEBUG (Motorola 68881 double 
, precision, 64-bit)! 
DSC$K_DTYPE_M68_ X 49 Reserved to DEBUG (Motorola 68881 extended 
precision, 96-bit)” 
DSC$K_DTYPE_1750_S 50 Reserved to DEBUG (1750 single precision, 32-bit) © 
DSC$K_DTYPE_1750_X 51 Reserved to DEBUG (1750 extended precision, 48-bit) 
DSC$K_DTYPE_WC 56 Reserved to DEBUG (setlocale dependent C string) 
No symbol defined 36 Obsolete 
DSC$K_DTYPE_T2 38 Obsolete 
DSC$K_DTYPE_VT2 39 Obsolete 


1Differs from Alpha IEEE floating because of byte ordering. 
Differs from Alpha IEEE floating because of byte ordering and size. 


4.4.1 Facility-Specific Data-Type Codes 


Data-type codes 160 through 191 are reserved to Digital for facility-specific 
purposes. These codes must not be passed between facilities because different 
facilities can use the same code for different purposes. These codes might be 
used by compiler-generated code to pass parameters to the language-specific 
run-time support procedures associated with that language or with the OpenVMS 
Debugger. 


As shown in Table 4-4, data-type codes 31 and 64 are reserved for the COBOL 
facility. Codes 40 through 51 and 56 are reserved for the OpenVMS Debugger 
facility. 


4.5 Varying Character String Data Type (DSC$K_DTYPE_VT) 


The varying character string data type (DSC$K_DTYPE_VT) consists of the 
following two fixed-length areas allocated contiguously with no padding in 
between (see Figure 4-1): 
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CURLEN An unsigned word specifying the current length in bytes of the immediately 
following string. , 


BODY A fixed-length area containing the string that can vary from zero to a 
maximum length defined for each instance of string. The range of this 
maximum length is 0 to 2'6 — 1. 


Figure 4-1 Varying Character String Data Type (DSC$K_DTYPE_VT)—General 
Format 


CURLEN (=n) 





ZK-7975A-GE 


When passed by reference or by descriptor, the address of the varying character 
string (VT) data type is always the address of the CURLEN field, not the BODY 
field. 


When a called procedure modifies a varying character string data type passed 
by reference or by descriptor, it writes the new length, n, into CURLEN and can 
modify all bytes of BODY, even those beyond the new length. 


For example, consider a varying string with a maximum length of seven 
characters. To represent the string ABC, CURLEN will have a value of 3 and the 
last four bytes will be undefined, as shown in Figure 4—2. 
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Figure 4-2 Varying Character String Data Type (DSC$K_DTYPE_VT) Format 





ZK-1889-GE 
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OpenVMS Argument Descriptors 


This chapter describes the argument descriptors used in calling a procedure for 
both VAX and Alpha environments. 


A uniform descriptor mechanism is defined for use by all VAX and Alpha 
procedures that conform to the OpenVMS calling standard. Descriptors are 
self-describing and the mechanism is extensible. When existing descriptors fail to 
satisfy the semantics of a language, new descriptors are added to this standard. 


Unless stated otherwise, the calling program fills in all fields in descriptors. This 
is true whether the descriptor is generated by default or by a language extension. 
The fields are filled in even if a called procedure written in the same language 
ignores the contents of some of the fields. Therefore, a descriptor conforms to this 
calling standard if all fields are filled in by the calling program, even if the called 
program does not need the field. 


Note 


Unless stated otherwise, all fields in descriptors represented as unsigned 
quantities are read-only from the point of view of the called procedure, 
and can be allocated in read-only memory at the option of the calling 
program. 


If a language processor implements a language-specific data type that is not 
added to this standard (see Chapter 4), the processor is not required to use a 
standard descriptor to pass an array of such a data type. However, if a language 
processor passes an array of such a data type using a standard descriptor, the 
language processor fills in the DSC$B_DTYPE field with zero, indicating that the 
data-type field is unspecified, rather than using a more general data-type code. 


For example, an array of PL/I POINTER data types has the DTYPE field filled in 
with the value 0 (unspecified data type), rather than with the value 4 (longword 
[unsigned] data type). The remaining fields are filled in as specified by this 
standard; for example, DSC$W_LENGTH is filled in with the size in bytes. 
Because the language-specific data type might be added to the standard in the 
future, generic application procedures that examine the DTYPE field should be 
prepared for zero and for additional data types. 


Table 5-1 identifies the classes of argument descriptors for use in the standard 
VAX and Alpha environments. Each class has two synonymous names—one 
for 32-bit environments (DSC$) and one for 64-bit environments (DSC64$). 
Descriptions and formats of each of these descriptors follow. 


5-1 


OpenVMS Argument Descriptors 


Table 5-1 Argument Descriptor Classes for OpenVMS Alpha and OpenVMS VAX 


Descriptor Code Class 

DSC$K_CLASS_S 1 Fixed-length scalar/string 
DSC64$K_CLASS_S 

DSC$K_CLASS_D . 2 Dynamic string 
DSC64$K_CLASS_D 
DSC$K_CLASS_A 4 Contiguous array 
DSC64$K_CLASS_A 

DSC$K_CLASS P! 5 Procedure argument descriptor 
DSC64$K_CLASS_P? 

DSC$K_CLASS_SD 9 Decimal (scalar) string 
DSC64$K_CLASS_SD 

DSC$K_CLASS_NCA 10 Noncontiguous array 
DSC64$K_CLASS_NCA 

DSC$K_CLASS_VS 11 Varying string 
DSC64$K_CLASS_VS 

DSC$K_CLASS_VSA 12 Varying string array 
DSC64$K_CLASS_VSA 

DSC$K_CLASS_UBS 13 Unaligned bit string 
DSC64$K_CLASS_UBS 

DSC$K_CLASS_UBA 14 Unaligned bit array 
DSC64$K_CLASS_UBA 

DSC$K_CLASS_SB 15 String with bounds 
DSC64$K_CLASS_SB 

DSC$K_CLASS_UBSB 16 Unaligned bit string with bounds 


DSC64$K_CLASS_UBSB 


1The pointer field usage for this descriptor differs from VAX usage (see Section 5.5). 


5.1 Descriptor Prototype 
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Figure 5-1 shows the descriptor prototype format. There are two forms: one for 
use with 32-bit addresses and one for use with 64-bit addresses. The two forms 
are compatible in that the forms can be distinguished dynamically at run time 
and, except for the size and consequential placement of fields, 32-bit and 64-bit 
descriptors are identical in content and interpretation. 


The 32-bit descriptors are used on both OpenVMS VAX and OpenVMS Alpha 
systems. When used on OpenVMS Alpha systems, 32-bit descriptors provide 
full compatibility with their use on OpenVMS VAX. The 64-bit descriptors are 
used only on OpenVMS Alpha systems—they have no counterparts and are not 
recognized on OpenVMS VAX systems. 
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Figure 5—1 Descriptor Prototype Format 


32-Bit Form (DSC) 


CLASS DTYPE LENGTH :0 
- POINTER 74 


ZK-4663A-GE 





64—Bit Form (DSC64) 
quadword aligned 


CLASS DTYPE MBO (=1) 0 
MBMO (=-1) 4 


8 
LENGTH 

716 
POINTER 


ZK-7656A-GE 
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The 32-bit descriptors on OpenVMS Alpha systems have no required alignment 
for compatibility with OpenVMS VAX systems; however, longword alignment 
generally promotes performance. The 64-bit descriptors on OpenVMS Alpha 
systems must be quadword aligned. 


Table 5-2 describes the fields of the descriptor. In this table and the similar 
tables for descriptors in later sections, note that most fields have two symbols 
and one description. The symbol that begins with the prefix DSC$ is used with 
32-bit descriptors, while the symbol that begins with the prefix DSC64$ is used 
with 64-bit descriptors. 


In this chapter, it is generally the practice to use only the main part of a 

field name, without either of the prefixes used in actual code. For example, 

the length field is referred to using LENGTH rather than mentioning both 
DSC$W_LENGTH and DSC64$Q_LENGTH. The DSC$ and DSC64$ prefixes are 


used only when referring to a particular form of descriptor. 


The CLASS and DTYPE fields occupy the same offsets in both 32-bit and 64-bit 
descriptors. Thus, the symbols DSC$B_CLASS and DSC64$B_CLASS have the 
same definition, as do DSC$B_DTYPE and DSC64$B_DTYPE. Furthermore, 
these fields are permitted to contain the same values with the same meanings in 
both 32-bit and 64-bit forms. 


OpenVMS Argument Descriptors 
5.1 Descriptor Prototype 
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The DSC$W_LENGTH and DSC$A_POINTER fields in the 32-bit descriptors 
correspond in placement to the DSC64$W_MBO (must be one) and DSC64$L_ 
MBMO (must be minus one) fields in the 64-bit descriptors. The values of these 
fields are used to distinguish whether a given descriptor has the 32-bit or 64-bit 
form as described later in this section. 


When the CLASS field is zero, no more information can be assumed than is 
shown in Table 5-2. 


Table 5-2 Contents of the Prototype Descriptor 


Symbol Description 

DSC$W_LENGTH Defines the data item length specific to the descriptor class. 
DSC64$Q_LENGTH 

DSC64$W_MBO In a 64-bit descriptor, this field must contain the value one. This 


field overlays the DSC$W_LENGTH field of a 32-bit descriptor 
and the value 1 is necessary to correctly distinguish between the 
two forms (see below). 


DSC$B_DTYPE A data-type code. Data-type codes are listed in Sections 4.1 and 

DSC64$B_DTYPE 4.2. 

DSC$B_CLASS A descriptor class code that identifies the format and 

DSC64$B_CLASS interpretation of the other fields of the descriptor as specified 
in the following sections. This interpretation is intended to be 
independent of the DTYPE field, except for the data types that 
are made up of units less than a byte (packed-decimal string 
[P], aligned bit string [V], and unaligned bit string [VU]). The 
CLASS code can be used at run time by a called procedure to 
determine which descriptor is being passed. 

DSC$A_POINTER The address of the first byte of the data element described. 

DSC64$PQ_ POINTER 

DSC64$L_MBMO In a 64-bit descriptor, this field must contain the value —1 (all 


one bits). Note that this field overlays the DSC$A_POINTER 
field of a 32-bit descriptor and the value —1 is necessary to 
correctly distinguish between the two forms (see below). 


As previously mentioned, the MBO field (a word at offset 0) and the MBMO 
field (a longword at offset 4) are used to distinguish between a 32-bit and 64-bit 
descriptor. A called routine that is designed to handle both kinds of descriptors 
must do both of the following: 


¢ Confirm that the MBO field contains 1 
e Confirm that the MBMO field contains —1 


before concluding that it has a 64-bit form descriptor. 


Note 


It may seem sufficient to test just the MBMO field. However, that allows 
a 32-bit descriptor with a length of zero and an undefined pointer to be 
inadvertently treated as a 64-bit descriptor. 


If the MBMO field contains —1, then 0 and 1 are the only values of the 
MBO field that have defined interpretations. ¢ 
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5.2 Fixed-Length Descriptor (CLASS_S) 


A single descriptor class is used for scalar data and fixed-length strings. Any 
OpenVMS data type, except data type 34 (unaligned bit string), can be used 
with this descriptor. Figure 5-2 shows the format of a fixed-length descriptor. 
Table 5-3 describes the fields of the descriptor. 


Figure 5-2 Fixed-Length Descriptor Format 


32-Bit Form (DSC) 


* CLASS (=1) DTYPE LENGTH : 
POINTER 


ZK~4664A~GE 














64-Bit Form (DSC64) 
quadword aligned 


MBMO (=~1) 


LENGTH | 
POINTER 


ZK-7657A-GE 
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Table 5-3 Contents of the CLASS_S Descriptor 
Symbol Description 


DSC$W_LENGTH Length of the data item in bytes, unless the DTYPE field 

DSC64$Q_ LENGTH contains the value 1 (aligned bit string) or 21 (packed-decimal 
string). Length of the data item is in bits for bit string. Length 
of the data item is the number of 4-bit digits (not including the 
sign) for a packed-decimal string. 


DSC64$W_MBO Must be 1. See Section 5.1. 
DSC$B_DTYPE A data-type code. Data-type codes are listed in Sections 4.1 and 
DSC64$B_DTYPE 4.2. 


(continued on next page) 


OpenVMS Argument Descriptors 
5.2 Fixed-Length Descriptor (CLASS_S) 


Table 5-3 (Cont.) Contents of the CLASS_S Descriptor 


Symbol Description 

DSC$B_CLASS Defines the descriptor class code that must be equal to 1 for 
DSC64$B_CLASS CLASS_S. 

DSC$A_POINTER Address of first byte of data storage. 

DSC64$PQ_POINTER 

DSC64$L_MBMO Must be -1. See Section 5.1. 


If the data type is 14 (character string) and the string must be extended in a 
string comparison or is being copied to a fixed-length string containing a greater 
length, the space character (hexadecimal 20 if ASCII) is used as the fill character. 


5.3 Dynamic String Descriptor (CLASS_D) 


A class D descriptor is used for dynamically allocated strings. When a string 

is written, either the length field, pointer field, or both can be changed. The 
OpenVMS Run-Time Library provides procedures for changing fields. As an input 
parameter, this format is interchangeable with class 1 (CLASS_S). Figure 5-3 


shows the format of a dynamic string descriptor. Table 5-4 describes the fields of 
the descriptor. 


Figure 5-3 Dynamic String Descriptor Format 
32-Bit Form (DSC) 


CLASS (=2) DTYPE LENGTH 
POINTER 
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64—Bit Form (DSC64) 
quadword aligned 


MBMO (=-1) 


LENGTH 
POINTER 


ZK-7658A-GE 
« 
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Table 5-4 Contents of the CLASS_D Descriptor 
Symbol Description 


DSC$W_LENGTH Length of the data item in bytes, unless the DTYPE field 

DSC64$Q_LENGTH contains the value 1 (aligned bit string) or 21 (packed-decimal 
string). Length of the data item is in bits for the bit string. 
Length of the data item is the number of 4-bit digits (not 
including the sign) for a packed-decimal string. 


DSC64$W_MBO Must be 1. See Section 5.1. 

DSC$B_DTYPE A data-type code. Data-type codes are listed in Sections 4.1 and 
DSC64$B_DTYPE 4.2. 

DSC$B_CLASS Defines the descriptor class code that must be equal to 2 for 
DSC64$B_CLASS CLASS_D. 

DSC$A_POINTER - Address of first byte of data storage. 

DSC64$PQ_POINTER 

DSC64$L_MBMO Must be —1. See Section 5.1. 


5.4 Array Descriptor (CLASS_A) 


The array descriptor shown in Figure 5-4 is used to describe contiguous arrays 
of atomic data types or contiguous arrays of fixed-length strings. An array 
descriptor consists of three contiguous blocks. The first block contains the 
descriptor prototype information and is part of every array descriptor. The second 
and third blocks are optional. If the third block is present, so is the second. 
Table 5-5 describes the fields of the descriptor. 
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Figure 5—4 Array Descriptor Format 


32-Bit Form (DSC) 


DIMCT AFLAGS DIGITS SCALE 
ARSIZE 


AO 116 





Block 1 
‘8 = (Prototype) 










12 





1 :20 


Block 2 
(Multipliers) 


M (n-1) 


L :20+4n 


U 124+44n 


Block 3 
(Bounds) 


n 


: ! , ! 


ZK-4666A-GE 


(continued on next page) 
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Figure 5-4 (Cont.) Array Descriptor Format 


64-Bit Form (DSC64) 
(Alpha Specific) 
quadword aligned 


eed 


LENGTH 
Block 1 
(Prototype) 
16 
POINTER 


DIMCT AFLAGS DIGITS SCALE i 
. 


ARSIZE 





740 
AO 
48 
e Block 2 
| : | (Multipliers) 
:484+8n 
L1 
:56+8n 
U1 
.. Block 3 
: (Bounds) 
Ln 
Un 
ZK-7659A-GE 


5-9 


OpenVMS Argument Descriptors 


5.4 Array Descriptor (CLASS_A) 


5-10 


Table 5-5 Contents of the CLASS_A Descriptor 


Symbol 


DSC$W_LENGTH. 
DSC64$Q_LENGTH 


DSC64$W_MBO 


DSC$B_DTYPE 
DSC64$B_DTYPE 


DSC$B_CLASS 
DSC64$B_CLASS 


DSC$A_POINTER 
DSC64$PQ_POINTER 


DSC64$L_MBMO 


DSC$B_SCALE 
DSC64$B_SCALE 


DSC$B_DIGITS 
DSC64$B_DIGITS 


DSC$B_AFLAGS 
DSC64$B_AFLAGS 


Description 


Length of an array element in bytes, unless the DTYPE field 
contains the value 1 (aligned bit string) or 21 (packed-decimal 
string). Length of an array element is in bits for the bit string. 
Length of an array element is the number of 4-bit digits (not 
including the sign) for a packed-decimal string. 


Must be 1. See Section 5.1. 


A data-type code. Data-type codes are listed in Sections 4.1 and 
4.2. 


Defines the descriptor class code that must be equal to 4 for 
CLASS_A. 


Address of the first actual byte of data storage. 


Must be —1. See Section 5.1. 


Signed power-of-two or power-of-ten multiplier, as specified by 
FL_BINSCALE, to convert the internal form to external form. 
(See Section 5.6.) 


If nonzero, the unsigned number of decimal digits in the internal 
representation. If zero, the number of digits can be computed 
based on LENGTH. This field should be zero unless the TYPE 
field specifies a string data type that could contain numeric 
values. 


Array flag bits <23:16>: 
Bits <18:16> 


DSC$V_FL_BINSCALE 
DSC64$V_FL_BINSCALE 


Reserved and must be zero. 


If set, the scale factor specified by 
SCALE is a signed power-of-two 
multiplier to convert the internal 
form to external form. If not 

set, SCALE specifies a signed 
power-of-ten multiplier. (See 
Section 5.6.) 


If set, the array can be 
redimensioned; that is, AO, Mz, 
Li, and Ui can be changed. The 
redimensioned array cannot 
exceed the size allocated to the 
array ARSIZE. 


If set, the elements of the 

array are stored by columns 
(FORTRAN). That is, the leftmost 
subscript (first dimension) 

is varied most rapidly, and 

the rightmost subscript (nth 
dimension) is varied least rapidly. 
If not set, the elements are stored 
by rows (most other languages). 
That is, the rightmost subscript 
is varied most rapidly and the 
leftmost subscript is varied least 
rapidly. 


DSC$V_FL_REDIM 
DSC64$V_FL_REDIM 


DSC$V_FL_COLUMN 
DSC64$V_FL_COLUMN 


(continued on next page) 
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Table 5-5 (Cont.) Contents of the CLASS_A Descriptor 


Symbol 


DSC$B_DIMCT 
DSC64$B_DIMCT 


DSC$L_ARSIZE 
DSC64$Q_ARSIZE 


DSC$A_AO 
DSC64$PQ_A0 


DSC$L_Mi 
DSC64$Q_Mi 
DSC$L_Li 
DSC64$Q_Li 
DSC$L_Ui 
DSC64$Q_Ui 


Description 


DSC$V_FL_COEFF 
DSC64$V_FL_COEFF 


If set, the multiplicative 
coefficients in block 2 are present. 
Must be set if FL_BOUNDS is 


set. 


DSC$V_FL_BOUNDS 
DSC64$V_FL_BOUNDS 


If set, the bounds information in 
block 3 is present and requires 
that FL_COEFF be set. 


Number of dimensions, n. 


Total size of array (in bytes, unless the TYPE field contains the 
value 21; see the description for LENGTH). A redimensioned 
array can use less than the total size allocated. 


For data type 1 (aligned bit string), LENGTH is in bits while 
ARSIZE is in bytes because the unit of length is bits, while the 
unit of allocation is aligned bytes. 


Address of element A(0,0, ... ,0). This need not be within the 
actual array. It is the same as POINTER for zero-origin arrays. 
Addressing coefficients ( Mz = Ui — Li +1 ). 


Lower bound (signed) of ith dimension. 


Upper bound (signed) of ith dimension. 


The following formulas specify the effective address, E, of an array element. 


Caution 


Modification of the following formulas is required if DTYPE contains a 
1 or 21, because LENGTH is given in bits or 4-bit digits rather than in 


bytes. 


The effective address, E, for element A(I): 


E 


Ao + I*LENGTH 
POINTER + [I - L1]*LENGTH 


The effective address, E, for element A(Ij,I9) with FL_COLUMN clear: 


E = Ag + [I1*M2 + I2]*LENGTH 
= POINTER + [[I1 - L1]*M2 + Iz - L2]*LENGTH 


The effective address, E, for element A(I;,I9) with FL_COLUMN set: 


E 


Ao + [I2*M] + I1]*LENGTH 
POINTER + [[I2 - Lo]*M] + Iq - L1]*LENGTH 


The effective address, E, for element A(Ij,. . 


. ln) with FL_COLUMN clear: 


E= Ao + C{[{[-+-(L1]*M2 + «--]*Mn-2 + In-2]*Mn-1 
+ In--1]*Mn + Ipn]*LENGTH 
= POINTER + [[[[-.--[1I1 - L1]*M2 
+ eee) *Mn-2 + In-2 - Ln-2]*Mn--1 
+ In--1 - Ln--1]*Mp + In - Ly) *LENCTH 
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The effective address, E, for element A(I},... In) with FL_COLUMN set: 


E= Ag + [[[[++-(In]*Mn--1 + ---]*M3 + 13]*Mo + I2]*M] + 1]]*LENGTH 
= POINTER + [[[[---{In - Ln] *Mn--1 + .--]*M3 + 13 
~ L3]*M2 + I2 - L2]*Mj + Iy - L1]*LENGTH 


5.5 Procedure Argument Descriptor (CLASS_P) 
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A descriptor for a procedure argument identifies a procedure and its result data 
type, if any. 


On VAX processors, the descriptor for a procedure argument specifies its entry 
address and function value data type. On Alpha processors, the procedure 
argument descriptor is a pointer to the procedure descriptor, which is described 
in Section 3.4. Figure 5-5 shows the format of a procedure argument descriptor. 
Table 5-6 describes the fields of the descriptor. 


Figure 5-5 Procedure Argument Descriptor Format 


32-Bit Form (DSC) 


CLASS (=5) DTYPE LENGTH 
POINTER : 


ZK-4675A-GE 











64-Bit Form (DSC64) 
quadword aligned 


LENGTH 
POINTER 
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716 
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Table 5-6 Contents of the CLASS_P Descriptor 


Symbol Description 

DSC$W_LENGTH Length associated with the function value, or zero if no function 

DSC64$Q_ LENGTH value is returned. 

DSC64$W_MBO Must be one. See Section 5.1. 

DSC$B_DTYPE Function value data type code. Data type codes are listed in 

DSC64$B_DTYPE Sections 4.1 and 4.2. 

DSC$B_CLASS Defines the descriptor class code that must be equal to 5 for 

DSC64$B_CLASS CLASS_P. 

DSC$A_POINTER Address of entry mask to the procedure for VAX environments. 
' DSC64$PQ_POINTER Address of the procedure descriptor of the procedure for Alpha 

environments. 
DSC64$L_MBMO Must be minus one. See Section 5.1. 


Procedures return a function value as described in Section 2.5 for VAX or 
Section 3.8.7 for Alpha. 


5.6 Decimal String Descriptor (CLASS_SD) 


Figure 5-6 shows the format of a decimal string descriptor. Decimal size and 
scaling information for both scalar data and simple strings is given in this 
descriptor form. Table 5—7 describes the fields of the descriptor. 


Figure 5-6 Decimal String Descriptor Format 


32-Bit Form (DSC) 


POINTER 


ZK-4668A-GE 












(continued on next page) 
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Figure 5-6 (Cont.) Decimal String Descriptor Format 


64-Bit Form (DSC64) 


quadword aligned 


Case [ome [=a | 
MBMO (=-1) 


LENGTH 


POINTER 


Reserved SFLAGS DIGITS SCALE : 
ed 





ZK-7661A-GE 


4 


Table 5-7 Contents of the CLASS_SD Descriptor 


Symbol 


DSC$W_LENGTH 
DSC64$Q_LENGTH 


DSC64$W_MBO 


DSC$B_DTYPE 
DSC64$B_DTYPE 


DSC$B_CLASS 
DSC64$B_CLASS 


DSC$A_POINTER 
DSC64$PQ_POINTER 


DSC64$L_MBMO 


DSC$B_SCALE 
DSC64$B_SCALE 


Description 


Length of the data item in bytes, unless the DTYPE field 
contains the value 1 (aligned bit string) or 21 (packed-decimal 
string). Length of the data item is in bits for the bit string. 
Length of the data item is the number of 4-bit digits (not 
including the sign) for packed-decimal string. 


Must be one. See Section 5.1. 
A data-type code. Data-type codes are listed in Sections 4.1 and 
4.2. 


Defines the descriptor class code that must be equal to 9 for 
CLASS_SD. 


Address of the first byte of data storage. 


Must be minus one. See Section 5.1. 


Signed power-of-two or power-of-ten multiplier, as specified by 
FL_BINSCALE, to convert the internal form to external form. 
(See examples in Table 5-8.) 
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Table 5-7 (Cont.) Contents of the CLASS_SD Descriptor 


Symbol Description 
DSC$B_DIGITS If nonzero, the unsigned number of decimal digits in the internal 
DSC64$B_DIGITS representation. If zero, the number of digits can be computed 


based on LENGTH. This field should be zero unless the TYPE 
field specifies a string data type that could contain numeric 


values. 

DSC$B_SFLAGS Scalar flag bits <23:16>: 

DSC64$B_SFLAGS Bits <18:16> Reserved and must be zero. 
DSC$V_FL_BINSCALE If set, the scale factor specified by 


DSC64$V_FL_BINSCALE SCALE is a signed power-of-two 
multiplier to convert the internal 
form to external form. If not set, 
SCALE specifies a signed power- 
of-ten multiplier. (See examples 
in Table 5-8.) 


Bits: <23:20> Reserved and must be zero. 


Examples of SCALE and FL_BINSCALE interpretation are presented in 
Table 5-8. 


Table 5-8 Internal-to-External BINSCALE Conversion Examples 


Internal Value SCALE FL_BINSCALE External Value 
123 +1 0 1230 
123 +1 1 246 
200 -2 0 2 
200 —2 1 50 


5.7 Noncontiguous Array Descriptor (CLASS_NCA) 


The noncontiguous array descriptor describes an array in which the storage of the 
array elements can be allocated with a fixed, nonzero number of bytes separating 
logically adjacent elements. Two elements are said to be logically adjacent if their 
subscripts differ by 1 in the most rapidly varying dimension only. The difference 
between the addresses of two adjacent elements is termed the stride. You can 
align elements by row or column, because the accessing algorithm in the called 
procedure handles both alignments. 


This array descriptor is to be used where the calling program, at its option, can 
pass a slice of an array that contains noncontiguous allocations. This standard 
indicates no preference between the noncontiguous array descriptor (NCA) and 
the contiguous array descriptor (A), as described in Section 5.4, for language 
processors that always allocate contiguous arrays. Figure 5—7 shows the format 
of a noncontiguous array descriptor, which consists of three contiguous blocks. 
Table 5-9 describes the fields of the descriptor. 
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Figure 5-7 Noncontiguous Array Descriptor Format 


32-Bit Form (DSC) 





:0 





4 
Block 1 
‘8 (Prototype) 










712 





Block 2 
(Strides) 


Block 3 
(Bounds) 
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Figure 5~7 (Cont.) Noncontiguous Array Descriptor Format 


64-Bit Form (DSC64) 


INphe Specie) quadword aligned 


CLASS (=10) DTYPE MBO (=1) 


LENGTH 


16 
POINTER 


DIMCT AFLAGS DIGITS SCALE 24 


ARSIZE 


















Block 1 
(Prototype) 


28 


32 


40 


48 


Block 2 
(Strides) 


S (n-1) 


n 


:48+8n 
L 


56+8n 


Block 3 
(Bounds) 


L 


n 
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Table 5-9 Contents of the CLASS_NCA Descriptor 


- Symbol 


DSC$W_LENGTH 
DSC64$Q_LENGTH 


DSC64$W_MBO 


DSC$B_DTYPE 
DSC64$B_DTYPE 


DSC$B_CLASS 


DSC$A_POINTER 
DSC64$PQ_POINTER 


DSC64$L_MBMO 


DSC$B_SCALE 
DSC64$B_SCALE 


DSC$B_DIGITS 


~ DSC64$B_DIGITS 


DSC$B_AFLAGS 
DSC64$B_AFLAGS 


DSC$B_DIMCT 
DSC64$B_DIMCT 


DSC$V_FL_REDIM 


Description 


Length of an array element in bytes, unless the DTYPE field 
contains the value 1 (aligned bit string) or 21 (packed-decimal 
string). Length of an array element is in bits for the bit string. 
Length of an array element is the number of 4-bit digits (not 
including the sign) for a packed-decimal string. 


Must be one. See Section 5.1. 
A data-type code. Data-type codes are listed in Sections 4.1 and 
4.2. 


Defines the descriptor class code that must be equal to 10 for 
CLASS_NCA. 


Address of first actual byte of data storage. 


Must be minus one. See Section 5.1. 


Signed power-of-two or power-of-ten multiplier, as specified by 
FL_BINSCALE, to convert the internal form to external form. 
(See Section 5.6.) 


If nonzero, the unsigned number of decimal digits in the internal 
representation. If zero, the number of digits can be computed 
based on LENGTH. This field should be zero unless the TYPE 
field specifies a string data type that could contain numeric 
values. 


Array flag bits <23:16>: 


Bits <18:16> Reserved to Digital. Must be 


zero. 


DSC$V_FL_BINSCALE 


y If set, the scale factor specified by 
DSC64$V_FL_BINSCALE 


SCALE is a signed power-of-two 
multiplier to convert the internal 
form to external form. If not 
set, SCALE specifies a signed 
power-of-ten multiplier. (See 
Section 5.6.) 


Must be zero. 
DSC64$V_FL_REDIM 


DSC$V_FL_UNALLOC 
DSC64$V_FL_UNALLOC 


If set, the storage for the array 
described by this descriptor 

has not been allocated; the 
POINTER field must contain 
zero. If not set, storage for the 
array described by this descriptor 
has been allocated; the POINTER 
field may or may not be zero 
depending on the bounds of the 
array. (If the POINTER field 
contains a nonzero value, then 
this flag must not be set.) 


Reserved to Digital. Must be 
zero. 


Bits <23:22> 
Number of dimensions, n. 
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Table 5-9 (Cont.) Contents of the CLASS_NCA Descriptor 


Symbol 


DSC$L_ARSIZE 


Description 


If the elements are contiguous, ARSIZE is the total size of the 


DSC64$Q_ARSIZE array (in bytes, unless the DTYPE field contains the value 
21; see the description of LENGTH). If the elements are not 
allocated contiguously or if the program unit allocating the 
descriptor is uncertain whether the array is actually contiguous, 
the value placed in ARSIZE might be meaningless. 
For data type 1 (aligned bit string), LENGTH is in bits while 
ARSIZE is in bytes because the unit of length is in bits while the 
unit of allocation is in bytes. 

DSC$A_A0 Address of element A(0,0, ... ,0). This need not be within the 

DSC64$PQ_A0 actual array. It is the same as POINTER for zero-origin arrays. 
AO = POINTER — ( 81*L; + Se*Lo +... + S,*ILn) 

DSC$L_Si Stride of the ith dimension. The difference between the 

DSC64$Q_Si addresses of successive elements of the ith dimension. 

DSC$L_Li Lower bound (signed) of the ith dimension. 

DSC64$Q_Li 

DSC$L_Ui Upper bound (signed) of the ith dimension. 

DSC64$Q_Ui 


The following formulas specify the effective address, E, of an array element. 


Caution 


Modification of the following formulas is required if DTYPE equals 1 or 
21 because LENGTH is given in bits or 4-bit digits rather than bytes. 


The effective address, E, of A(]): 


E = Ag + S1*I 


= POINTER + $1*[I - L]] 
The effective address, E, of A(I,,I5): 


E = Ao + S1*I1 + SQ*I2 
= POINTER + S1*[Ij - Li] + S2*[1I2 - 12] 


The effective address, E, of A,.. . ,In): 


E 


Ao + Sy*Iz7 +. . 
POINTER + S1*[Ij - Lj] t+... + Sn*[In - Lp] 


ee eas 


5.8 Varying String Descriptor (CLASS_VS) 


A class VS descriptor is used for varying string data types (see Section 4.5). 


As an input parameter, this format is not interchangeable with class 1 (CLASS_S) 
or with class 2 (CLASS_D). When a called procedure modifies a varying string 
passed by reference or by descriptor, it writes the new length, n, into CURLEN 
and can modify all bytes of BODY. Figure 5-8 shows the format of a varying 
string descriptor. Table 5-10 describes the fields of the descriptor. | 
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Figure 5-8 Varying String Descriptor Format 


32-Bit Form (DSC) 


CLASS (=11) DTYPE MAXSTRLEN :0 
POINTER ‘4 


ZK-4669A-GE 





64-Bit Form (DSC64) 
quadword aligned 


CLASS tt 
MBMO (=-1) 


MAXSTRLEN 
POINTER 






ZK-7663A-GE 
¢ 
Table 5-10 Contents of the CLASS_VS Descriptor 
Symbol | Description 
DSC$W_MAXSTRLEN Maximum length of the BODY field of the varying string in 
DSC64$Q_MAXSTRLEN bytes in the range 0 to 2) — 1. 
DSC64$W_MBO Must be one. See Section 5.1. 
DSC$B_DTYPE A data type code that has the value 37, which specifies the 
DSC64$B_DTYPE varying character string data type (see Sections 4.2 and 4.5). 
The use of other data types is reserved to Digital. 
DSC$B_CLASS Defines the descriptor class code that must be equal to 11 for 
DSC64$B_CLASS CLASS_VS. 
DSC$A_POINTER Address of the first field (CURLEN) of the varying string. 
DSC64$PQ_POINTER 
DSC64$L_MBMO Must be minus one. See Section 5.1. 


Figure 5-9 illustrates the use of a 32-bit varying string descriptor to present a 
variable that is capable of holding a string value of up to five characters in length 
and that is currently holding the string value ABCD. As shown in the figure, 
MAXSTRLEN contains five, CURLEN contains four, string is currently ABCD, 
and the remaining byte is currently undefined. 
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Figure 5-9 Varying String Descriptor with Character String Data Type 


:descriptor 





ZK-1897-GE 


5.9 Varying String Array Descriptor (CLASS_VSA) 


A variant of the noncontiguous array descriptor is used to specify an array of 
varying strings where each varying string has the same maximum length. Each 
array element is of the varying string data type (see Section 4.5). 


When a called procedure modifies a varying string in an array of varying strings 
passed to it by reference or by descriptor, it writes the new length, n, into 
CURLEN and can modify all bytes of BODY. The format of this descriptor is the 
same as the noncontiguous array descriptor except for the first two longwords. 
Figure 5-10 shows the format of a varying string array descriptor. Table 5-11 
describes the fields of the descriptor. 
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Figure 5-10 Varying String Array Descriptor Format 


32-Bit Form (DSC) 


A :16 





:0 





4 






Block 1 
:8 (Prototype) 






12 





S1 :20 


Block 2 
(Multipliers) 


S (n-1) 


S 


L1 :20+4n 


U1 124+4n 


Block 3 
(Bounds) 


U 


| | | ! 
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Figure 5-10 (Cont.) Varying String Array Descriptor Format 


64-Bit Form (DSC64) 
(Alpha Specific) quadword aligned 


DTYPE MBO (=1) 






CLASS (=12) 





:0 
MBMO (=-1) 4 
8 
MAXSTRLEN 
. Block 1 


(Prototype) 
6 


ARSIZE 


Block 2 
(Multiptiers) 


Block 3 
(Bounds) 
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Table 5-11 Contents of the CLASS_VSA Descriptor 


Symbol Description 

DSC$W_MAXSTRLEN Maximum length of the BODY field of an array element in 

DSC64$Q_MAXSTRLEN bytes in the range 0 to 27° — 1. . 

DSC64$W_MBO Must be one. See Section 5.1. 

DSC$B_DTYPE A data-type code that has the value 37, which specifies the 

DSC64$B_DTYPE varying character string data type (see Sections 4.2 and 4.5). 
The use of other data types is reserved to Digital. 

DSC$B_CLASS Defines the descriptor class code that must be equal to 12 for 

DSC64$B_CLASS CLASS_VSA. 

DSC$A_POINTER Address of the first actual byte of data storage. 

DSC64$PQ_ POINTER 

DSC64$L_MBMO Must be minus one. See Section 5.1. 


The remaining fields in the descriptor are identical to those in the noncontiguous 
array descriptor (NCA). The effective address computation of an array element 
produces the address of CURLEN of the desired element. 


5.10 Unaligned Bit String Descriptor (CLASS_UBS) 
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A descriptor is used to pass an unaligned bit string (DSC$K_DTYPE_VU) that 
starts and ends on an arbitrary bit boundary. The descriptor provides two 
components: a base address and a signed relative bit position. Figure 5-11 shows 


the format of an unaligned bit string descriptor. Table 5-12 describes the fields of 
the descriptor. 


Figure 5-11 Unaligned Bit String Descriptor Format 


32-Bit Form (DSC) 


CLASS (=13) DTYPE LENGTH 
BASE 


ZK-4671A-GE 
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Figure 5-11 (Cont.) Unaligned Bit String Descriptor Format 
64-Bit Form (DSC64) 
quadword aligned 


MBMO (=-1) 


LENGTH 
716 
BASE 








124 
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Table 5-12 Contents of the CLASS_UBS Descriptor 
Symbol Description 
DSC$W_LENGTH Length of data item in bits. 
DSC64$Q_LENGTH 
DSC64$W_MBO Must be one. See Section 5.1. 
DSC$B_DTYPE A data-type code that has the value 34, which specifies the 
DSC64$B_DTYPE unaligned bit string data type (see Sections 4.1 and 4.2). The 
use of other data types is reserved to Digital. 
DSC$B_CLASS Defines the descriptor class code that must be equal to 13 for 
DSC64$B_CLASS CLASS_UBS. 
DSC$A_BASE Base of the address relative to which the signed relative bit 
DSC64$PQ_ BASE position, POS, is used to locate the bit string. The base address 
need not be the first actual byte of data storage. 
DSC64$L_MBMO Must be minus one. See Section 5.1. 
DSC$L_POS Relative bit position with respect to BASE of the first bit of 
DSC64$Q_ POS unaligned bit string. 


5.11 Unaligned Bit Array Descriptor (CLASS_UBA) 


A variant of the noncontiguous array descriptor is used to specify an array of 
unaligned bit strings. Each array element is an unaligned bit string data type 
(DSC$K_DTYPE_VU) that starts and ends on an arbitrary bit boundary. The 
length of each element is the same and is 0 to 216 — 1 bits. You can access 
elements of the array directly by using the VAX variable bit field instructions. 
Therefore, the descriptor provides two components: a byte address, BASE, and 
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a means to compute the signed bit offset, EB, with respect to BASE of an array 
element. 


The unaligned bit array descriptor consists of four contiguous blocks that are 
always present. The first block contains the descriptor prototype information. 
Figure 5-12 shows the format of an unaligned bit array descriptor. Table 5-13 
describes the fields of the descriptor. 


Figure 5-12 Unaligned Bit Array Descriptor Format 


32-Bit Form (DSC) 


Vo 716 










:0 


4 






Block 1 
:8 (Prototype) 






12 





:20 


Block 2 
(Strides) 


S (n-1) 


Sn 


:20+4n 


U 124+4n 


Block 3 
(Bounds) 


n 


n 


: : : : 


POS :24+8n Block 4 
(Position) 
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Figure 5-12 (Cont.) Unaligned Bit Array Descriptor Format 
arco 


CLASS (=14) DTYPE MBO (=1) 


MBMO (=~1) 


LENGTH 
Block 1 
(Prototype) 
16 
BASE 


quadword aligned 


DIMCT AFLAGS DIGITS SCALE : 
| 


ARSIZE 





:40 
V 


48 


Block 2 
(Strides) 


S (n-1) 


:48+8n 
L1 


:56+8n 
U 


Block 3 
(Bounds) 


L 


U 


} | } | } 


POS :56+16n 


Block 4 % 
(Position) 
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Table 5-13 Contents of the CLASS_UBA Descriptor 


Symbol 
DSC$W_LENGTH 
DSC64$Q_ LENGTH 
DSC64$W_MBO 


DSC$B_DTYPE 
DSC64$B_DTYPE 


DSC$B_CLASS 
DSC64$B_CLASS 


DSC$A_BASE 
DSC64$PQ_BASE 


DSC64$L_MBMO 


DSC$B_SCALE 
DSC64$B_SCALE 


DSC$B_DIGITS _ 
DSC64$B_DIGITS 


DSC$B_AFLAGS 
DSC64$B_AFLAGS 


DSC$B_DIMCT 
DSC64$B_DIMCT 


DSC$L_ARSIZE 
DSC64$Q_ARSIZE 


DSC$L_VO 
DSC64$Q_V0 
DSC$L_Si 
DSC64$Q_Si 
DSC$L_Li 
DSC64$Q_Li 


DSC$L_Ui 
DSC64$Q_Ui 


DSC$L_POS 
DSC64$Q_POS 


’ Bits <23:21> 


Description 


Length of an array element in bits. 


Must be one. See Section 5.1. 


A data-type code that must have the value 34, which specifies 
the unaligned bit string data type (see Sections 4.1 and 4.2). The 
use of other data types is reserved to Digital. 


Defines the descriptor class code that must be equal to 14 for 
CLASS_UBA. 
Base address relative to the effective bit offset, EB, that is used 


to locate elements of the array. The base address need not be 
the first actual byte of data storage. 


Must be minus one. See Section 5.1. 


Reserved to Digital. Must be zero. 


If nonzero, the unsigned number of decimal digits in the internal 
representation. If zero, the number of digits can be computed 
based on LENGTH. This field should be zero unless the TYPE 
field specifies a string data type that could contain numeric 
values. 


Array flag bits <23:16>: 


Bits <18:16> Reserved to Digital. Must be 


zero. 


DSC$V_FL_BINSCALE 
DSC64$V_FL_BINSCALE 


DSC$V_FL_REDIM 
DSC64$V_FL_REDIM 


Must be zero. 
Must be zero. 


Reserved to Digital. Must be 
zero. 


Number of dimensions, n. 


If the elements are contiguous, ARSIZE is the total size of the 
array in bits. If the elements are not allocated contiguously or if 
the program unit allocating the descriptor is uncertain whether 
the array is actually contiguous, the value placed in ARSIZE 
might be meaningless. 


Signed bit offset of element A(0, ... ,0) with respect to BASE. 
Vo = POS — [Si*Li +... + Sp*Ly]. 


Stride of the ith dimension. The difference between the bit (not 
byte) addresses of successive elements of the ith dimension. 


Lower bound (signed) of the ith dimension. 


Upper bound (signed) of the ith dimension. 


Relative bit position with respect to BASE of the first actual bit 
of the array, that is, element A(Li, ... ,L,). 
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The following formulas specify the signed effective bit offset, EB, of an array 
element: 


The signed effective bit offset, EB, of A(1,): 


EB = Vo + S1*Ij 
= POS + $1*[I1 - Lj] 


The signed effective bit offset, EB, of A(I1,I»): 


EB = Vo + S1*I1 + S2*I2 


POS + S1*[I1 - L1] + S2*[I2 - 12] 
The signed effective bit offset, EB, of AMj, ... , In): 


EB = Vo + Sj*Iz + ... + Sn*In 
= POS + Sq*[I1 - L1] +... + Sn*[In - Lp] 


Note that EB is computed ignoring integer overflow. 


On VAX systems, EB is used as the position operand, and the content of BASE is 
used as the base address operand in the VAX variable-length bit field instructions. 
Therefore, BASE must specify a byte within 27° bytes of all bytes of storage in 
the bit array. ¢ 


For example, consider a single-origin, one-dimensional, five-element array 
consisting of 3-bit elements allocated adjacently (therefore, S1 = 3). Assume 
BASE is byte 1000 and the first actual element, A(1), starts at bit <4> of byte 
1001. 


71000 
71001 
71002 


71003 
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The following dependent field values occur in the descriptor: 


12 
12 - 3*1 = 9 


5.12 String with Bounds Descriptor (CLASS_SB) 


A variant of the fixed-length string descriptor is used to specify strings where 
the string is viewed as a one-dimensional array with user-specified bounds. 
Figure 5-13 shows the format of a string with bounds descriptor. Table 5-14 
describes the fields of the descriptor. 
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Figure 5-13 String with Bounds Descriptor Format 
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64-Bit Form (DSC64) 
quadword aligned 


MBMO (=~1) 


LENGTH 
716 
POINTER 
SB_L1 
SB_U1 
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Table 5—14 Contents of the CLASS_SB Descriptor 
Symbol Description 

DSC$W_LENGTH Length of the string in bytes. 
DSC64$Q_LENGTH 

DSC64$W_MBO Must be one. See Section 5.1. 


DSC$B_DTYPE A data-type code that must have the value 14, which specifies 
DSC64$B_DTYPE the character string data type (see Sections 4.1 and 4.2). The 
use of other data types is reserved to Digital. 
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Table 5-14 (Cont.) Contents of the CLASS_SB Descriptor 


Symbol Description 

DSC$B_CLASS Defines the descriptor class code that must be equal to 15 for 
DSC64$B_CLASS | CLASS_SB. 

DSC$A_POINTER Address of the first byte of data storage. 
DSC64$PQ_POINTER 

DSC64$L_MBMO Must be minus one. See Section 5.1. 

DSC$L_SB_L1 Lower bound (signed) of the first (and only) dimension. 
DSC64$Q_SB_L1 

DSC$L_SB_U1 Upper bound (signed) of the first (and only) dimension. 


DSC64$Q_SB_U1 


The following formula specifies the effective address, E, of a string element A(1): 


E = POINTER + [I - SB Ll] 


If the string must be extended in a string comparison or assignment, the space 
character (hexadecimal 20 if ASCII) is used as the fill character. 


5.13 Unaligned Bit String with Bounds Descriptor (CLASS_UBSB) 


A variant of the unaligned bit string descriptor is used to specify bit strings 
where the string is viewed as a one-dimensional bit array with user-specified 
bounds. Figure 5—14 shows the format of an unaligned bit string with bounds 
descriptor. Table 5—15 describes the fields of the descriptor. 


Figure 5-14 Unaligned Bit String with Bounds Descriptor Format 


32-Bit Form (DSC) 


Pesce [oe [amd 
ee 
| 
ee 
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Figure 5-14 (Cont.) Unaligned Bit String with Bounds Descriptor Format 


64-Bit Form (DSC64) 
quadword aligned 









:8 
LENGTH 
:16 
BASE 
124 
POS 
32 
UBSB_L1 
40 
UBSB_U1 
ZK-7667A-GE 
¢ 
Table 5-15 Contents of the CLASS_UBSB Descriptor 
Symbol Description 
DSC$W_LENGTH Length of the data item in bits. 
DSC64$Q_LENGTH 
DSC64$W_MBO Must be one. See Section 5.1. 
DSC$B_DTYPE A data-type code that must have the value 34, which specifies 
DSC64$B_DTYPE the unaligned bit string data type (see Sections 4.1 and 4.2). 
The use of other data types is reserved to Digital. 
DSC$B_CLASS Defines the descriptor class code that must be equal to 16 for 
DSC64$B_CLASS CLASS_UBSB. 
DSC$A_BASE Base address relative to the signed relative bit position, POS, 
DSC64$PQ_BASE used to locate the bit string. The base address need not be the 
first actual byte of data storage. 
DSC64$L_MBMO Must be minus one. See Section 5.1. 
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Table 5-15 (Cont.) Contents of the CLASS_UBSB Descriptor 


Symbol Description 

DSC$L_POS Signed longword that defines the relative bit position of the 
DSC64$Q_POS first bit of the unaligned bit string to the BASE address. 
DSC$L_UBSB_L1 Lower bound (signed) of the first (and only) dimension. 
DSC64$Q_UBSB_L1 

DSC$L_UBSB_U1 Upper bound (signed) of the first (and only) dimension. 


DSC64$Q_UBSB_U1 


The following formula specifies the effective bit offset, EB, of a bit element A(I): 
EB = POS + [I - UBSB_L1] 


5.14 Reserved Descriptor Class Codes 


All descriptor class codes from 0 through 191 not otherwise defined in this 
standard are reserved to Digital. Classes 192 through 255 are reserved to 
Digital’s Computer Special Systems Group and customers. 


Table 5-16 lists some specific descriptor classes and codes that are obsolete or 
reserved to Digital. 


Table 5-16 Specific OpenVMS VAX Descriptors Reserved to Digital 


Descriptor Code Class 

DSC$K_CLASS_V . 3 Obsolete (variable buffer) 
DSC$K_CLASS_PI 6 Obsolete (procedure incarnation) 
DSC$K_CLASS_J < Reserved to DEBUG (label) 
DSC$K_CLASS_JI 8 Obsolete (label incarnation) 
DSC$K_CLASS_CT “17 Reserved to ACMS (compressed text) 
DSC$K_CLASS_BFA 191 Reserved to BASIC (file array) 


5.14.1 Facility-Specific Descriptor Class Codes 


Descriptor class codes 160 through 191 are reserved to Digital for facility-specific 
purposes. These codes must not be passed between facilities, because different 
facilities might use the same code for different purposes. These codes can be used 
by compiler-generated code to pass parameters to the language-specific, run-time 
support procedures associated with that language or to the OpenVMS Debugger. 
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An OpenVMS condition is a hardware-generated synchronous exception or a 
software event that is to be processed in a manner similar to a VAX or an Alpha 
hardware exception. 


Floating-point overflow exception, memory access violation exception, and 
reserved operation exception are examples of hardware-generated conditions. An 
output conversion error, an end of file, and the filling of an output buffer are 
examples of software events that might be treated as conditions. 


Depending on the condition and on the program, you can exercise any of four 
types of action when a condition occurs: 


e Ignore the condition. 


For example, if an underflow occurs in a floating-point operation, continuing 
from the point of the exception with a zero result might be sufficient. 


e Take some special action and continue from the point at which the condition 
occurred. 


For example, if the end of a buffer is reached while a series of data items are 
being written, the special action is to start a new buffer. 


¢ End the operation and branch from the sequential flow of control. 


For example, if the end of an input file is reached, the branch exits from a 
loop that is processing the input data. 


e Treat the condition as an unrecoverable error. 


For example, when the floating divide-by-zero exception condition occurs, the 
program exits after writing (optionally) an appropriate error message. 


When an unusual event or error occurs in a called procedure, the procedure 
can return a condition value to the caller indicating what has happened (see 
Section 6.1). The caller tests the condition value and takes the appropriate 
action. 


When an exception is generated by the hardware, a branch out of the program’s 
flow of control occurs automatically. In this case, and for certain software- 
generated events, it is more convenient to handle the condition as soon as it is 
detected rather than to program explicit tests. 

6.1 Condition Values 


Condition values are used in the OpenVMS operating system to provide the 
following functions: 


e Indicate the success or failure of a called procedure as a function value 


¢ Describe an exception condition when an exception is signaled 
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e Identify system messages 
e Report program success or failure to the command language level 


A condition value is a longword that includes fields to describe the software 
component that generates the value, the reason the value was generated, and 
severity status of the condition value. Figure 6-1 shows the format of a condition 
value. Table 6—1 describes the fields of a condition value. 


Figure 6-1 Format of a Condition Value 


oO . 


31 2827 3 2 


Condition identification Severity 
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Table 6-1 Contents of the Condition Value 


Symbol 


Severity 


Condition identification 


Message number 


Facility number 


Control 


Description 


Indicates success or failure. The severity code bit <0> is set 
for success (logical true) and is clear for failure (logical false); 
bits <1> and <2> distinguish degrees of success or failure. Bits 
<2:0>, when taken as an unsigned integer, are interpreted as 
shown in the following table: 


Symbol Value Description 
STS$K_WARNING 0 Warning 
STS$K_SUCCESS Success 
STS$K_ERROR Error 
STS$K_INFO Information 


STS$K_SEVERE Severe error 
Reserved to Digital 


Reserved to Digital 


NO oO fF OO ND 


Reserved to Digital 


Section 6.1.1 more fully describes severity codes. 
Identifies the condition uniquely on a systemwide basis. 


Describes the status, which can be a hardware exception that 
occurred or a software-defined value. Message numbers with 
bit <15>.set are specific to a single facility. Message numbers 
with bit <15> clear are systemwide status codes. 


Identifies the software component generating the condition 
value. Bit <27> is set for customer facilities and is clear for 
Digital facilities. 


Controls the printing of the message associated with the 
condition value. Bit <28> inhibits the message associated 
with the condition value from being printed by the SYS$EXIT 
system service. This bit is set by the system default handler 
after it has output an error message using the SYS$PUTMSG 
system service. It should also be set in the condition value 
returned by a procedure as a function value, if the procedure 
has also signaled the condition (so the condition has been 
printed or suppressed). Bits <31:29> must be zero; they are 
reserved to Digital for future use. 


Table 6—2 lists the possible software symbols that are defined 
for the various fields of the condition-value longword. 


Table 6-2 Value Symbols for the Condition Value Longword 


Symbol 


STS$V_COND_ID 
STS$S_COND_ID 
STS$M_COND_ID 
STS$V_INHIB_MSG 
STS$S_INHIB_MSG 


Value Meaning Field 
3 Position of 27:3 Condition identification 
25 Size of 27:3 Condition identification 
Mask Mask for 27:3 Condition identification 
1@28 Position for 28 Inhibit message on image exit 
1 Size for 28 Inhibit message on image exit 


(continued on next page) 
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6.1.1 Interpretation of Severity Codes 
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Table 6-2 (Cont.) Value Symbols for the Condition Value Longword 


Symbol Value Meaning Field 
STS$M_INHIB_MSG Mask Mask for 28 Inhibit message on image exit 
STS$V_FAC_NO 16 Position of 27:16 Facility number | 
STS$S_FAC_NO 12 Size of 27:16 Facility number 
STS$M_FAC_NO Mask Mask for 27:16 Facility number 
STS$V_CUST_DEF 27 Position for 27 Customer facility 
STS$S_CUST_DEF 1 Size for 27 Customer facility 
STS$M_CUST_DEF 1@27 Mask for 27 Customer facility 
STS$V_MSG_NO 3 Position of 15:3 Message number 
STS$S_MSG_NO 13 Size of 15:3 Message number 
STS$M_MSG_NO Mask Mask for 15:3 Message number 
STS$V_FAC_SP 15 Position of 15 Facility-specific 
STS$S_FAC_SP 1 Size for 15 Facility-specific 
STS$M_FAC_SP 1@15 Mask for 15 Facility-specific 
STS$V_CODE 3 Position of 14:3 Message code 
STS$S_CODE 12 Size of 14:3 Message code 
STS$M_CODE Mask Mask for 14:3 Message code 
STS$V_SEVERITY 0 Position of 2:0 Severity — 
STS$S_SEVERITY 3 Size of 2:0 Severity 
STS$M_SEVERITY a Mask for 2:0 Severity 
STS$V_SUCCESS 0 Position of 0 Success 
STS$S_SUCCESS 1 Size of 0 Success 
STS$M_SUCCESS A Mask for 0 Success 


A standard procedure must consider all possible severity codes (0-4) of a condition 
value. Table 6-3 lists the interpretation of severity codes 0 through 4. 


Table 6-3 Interpretation of Severity Codes 


Severity 

Code Meaning 

0 Indicates a warning. This code is used whenever a procedure produces output, 
but the output produced might not be what the user expected (for example, a 
compiler modification of a source program). 

1 Indicates that the procedure generating the condition value completed 
successfully, as expected. 

2 Indicates that an error has occurred but the procedure did produce output. 


Execution can continue, but the results produced by the component generating 
the condition value are not all correct. 
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Table 6-3 (Cont.) Interpretation of Severity Codes 


Severity 

Code Meaning 

3 Indicates that the procedure generating the condition value completed 
successfully but has some parenthetical information to be included in a 
message if the condition is signaled. 

4 Indicates that a severe error occurred and the component generating the 


condition value was unable to produce output. 


When designing a procedure, you should base the choice of severity code for its 
condition values on the following default interpretations: 


¢ The calling program typically performs a low-bit test, so it treats warnings, 
errors, and severe errors as failures and treats success and information as 
successes. 


e Ifthe condition value is signaled (see Section 6.4.3), the default handler treats 
severe errors as reason to terminate and treats all the others as the basis for 
continuation. 


¢ When the program image exits, the command interpreter by default treats 
errors and severe errors as the basis for stopping the job, and treats warnings, 
information, and successes as the basis for continuation. 


The following table summarizes the action default decisions of the severity 


conditions: 

Default at 
Severity Routine Signal Program Exit 
Success Normal Continue Continue 
Information Normal Continue Continue 
Warning Failure Continue Continue 
Error Failure Continue Stop job 
Severe error Failure Exit Stop job 


The default for signaled messages is to output a message with the SYS$OUTPUT 
system service. In addition, for severities other than success (STS$K_SUCCESS), 
a copy of the message is made on SYS$ERROR. At program exit, success and 
information completion values do not generate messages; however, warning, error, 
and severe error condition values do generate messages to SYS$OUTPUT and 
SYS$ERROR unless bit <28> (STS$V_INHIB_MSG) is set. 


Unless there is a good basis for another choice, a procedure should use success or 
severe error as its severity code for each condition value. 


6.1.2 Use of Condition Values 


OpenVMS software components return condition values when they complete 
execution.. When a severity code in the range of 0 through 4 is generated, the 
status code describes the nature of the problem. This value can be tested to 
change the flow of control of a procedure, used to generate a message, or both. 
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User procedures can also generate condition values to be examined by other 
procedures and by the command interpreter. User-generated condition values 
should have bits <27> and <15> set so they do not conflict with values generated 
by Digital. 


6.2 Condition Handlers 
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To handle hardware- or software-detected exceptions, the OpenVMS Condition 
Handling Facility (CHF) allows you to specify a condition handler procedure to be 
called when an exception condition occurs. . 


An active procedure can establish a condition handler to be associated with it. 
When an event occurs that is to be treated using the Condition Handling Facility, 
the procedure detecting the event signals the event by calling the facility and 
passing a condition value that describes the condition. This condition value has 
the format and interpretation described in Section 6.1. All hardware exceptions 
are signaled. . 


When a condition is signaled, the Condition Handling Facility looks for a 
condition handler associated with the current procedure’s stack frame. Ifa 
handler is found, it is entered. If a handler is not associated with the current 
procedure, the immediately preceding stack frame is examined. Again, if a 
handler is found, it is entered. If a handler is not found, the search of previous 
stack frames continues until the default condition handler established by the 
system is reached or until the stack runs out. 


The default condition handler prints messages indicated by the signal argument 
list by calling the put message (SYS$PUTMSG) system service, followed by an 
optional symbolic stack traceback. Success conditions with STS$K_SUCCESS 
result in messages to SYS$OUTPUT only. All other conditions, including 
informational messages (STS$K_INFO), produce messages on SYS$OUTPUT and 
SYS$ERROR. 


For example, if a procedure needs to keep track of the occurrence of the floating- 
point underflow exception, it can establish a condition handler to examine the 
condition value passed when the handler is invoked. Then, when the floating- 
point underflow exception occurs, the condition handler is entered and logs 

the condition. The handler returns to the instruction immediately following 

the instruction that was executing when the condition was reported by the 
hardware. On a VAX processor, this instruction is the one immediately following 
the instruction that caused the underflow; on an Alpha processor, this instruction 
might occur later. 


If floating-point operations occur in many procedures of a program, the condition 
handler can be associated with the program’s main procedure. When the 
condition is signaled, successive stack frames are searched until the stack frame 
for the main procedure is found, at which time the handler is entered. If a user 
program has not associated a condition handler with any of the procedures that 
are active at the time of the signal, successive stack frames are searched until the 
frame for the system program invoking the user program is reached. A default 
condition handler that prints an error message is then entered. 
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6.3 Condition Handler Options 


Each procedure activation potentially has a single condition handler associated 
with it. This condition handler is entered whenever any condition is signaled 
within that procedure. (It can also be entered as a result of signals within active 
procedures called by the procedure.) Each signal includes a condition value 

(see Section 6.1) that describes the condition that caused the signal. When the 
condition handler is entered, examine the condition value to determine the cause 
of the signal. After the handler either processes the condition or ignores it, it can 
take one of the following actions: 


Return to the instruction immediately following the signal. Note that such a 
return is not always possible. 


Resignal the same or a modified condition value. A new search for a condition 
handler begins with the immediately preceding stack frame. 


Signal a different condition. 
Unwind the stack. 


On Alpha systems, perform a nonlocal GOTO operation (see Section 6.4) that 
transfers control from one procedure invocation and continues execution in a 
prior one. ¢ 


6.4 Operations Involving Condition Handlers 


The OpenVMS Condition Handling Facility (CHF) provides functions to perform 
the following operations: 


UG 


Establish a condition handler. 


A condition handler is associated with a procedure in various ways, depending 
on the language in which the procedure is written. Some languages provide 
specific syntax for defining a handler and its possible actions; others allow 
dynamic specification of a routine to act as a handler. 


On VAX systems, revert to the caller’s handling. 


If a condition handler has been established on a VAX processor, you can 
remove it.¢ 


Enable or disable certain arithmetic exceptions. 


The software can enable or disable the following hardware exceptions: 
floating-point underflow, integer overflow, and decimal overflow. No signal 
occurs when the exception is disabled. 


On VAX systems, exceptions are enabled or disabled dynamically at every 
procedure entry or by directly manipulating the processor status longword.¢ 


On Alpha systems, exceptions are enabled or disabled statically during 
compilation; this is reflected in the code that is compiled. ¢ 


Signal a condition. . . 
Signaling a condition initiates the search for an established condition handler. 
Unwind the stack. 


Upon exiting from a condition handler, it is possible to remove one or more 
frames that occur before the signal from the stack. During the unwinding 
operation, the stack is scanned; if a condition handler is associated with a 
frame, the handler is entered before the frame is removed. Unwinding the 
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stack allows a procedure to perform application-specific cleanup operations 
before exiting. 


On Alpha systems, perform a nonlocal GOTO unwind. 


A GOTO unwind operation is a transfer of control that leaves one procedure 
invocation and continues execution in a prior (currently active) procedure. 
This unified GOTO operation gives unterminated procedure invocations the 
opportunity to clean up in an orderly way.¢ 


6.4.1 Establishing a Condition Handler 


<i> 





On VAX systems, the association of a handler with a procedure invocation is 
dynamic and can be changed or reverted to the caller’s handler during execution, 
although this is not supported for languages that implicitly provide their own 
handlers. 


Each procedure activation can have an associated condition handler, using 

the first longword in its stack frame. Initially, the first longword (longword 0) 
contains the value 0, indicating no handler. You establish a handler by moving 
the address of the handler’s procedure entry point mask to the establisher’s stack 
frame. 


On VAX systems, the following code establishes a condition handler: 
MOVAB handler entry point,0(FP)¢@ 


On Alpha systems, the association of a handler with a procedure is static and 
must be specified at the time a procedure is compiled (or assembled). However, 
some languages that lack their own exception-handling syntax can support 
emulation of dynamically specified handlers by means of built-in routines. 


Each procedure, other than a null frame procedure, can have a condition handler 
potentially associated with it, which is identified by the HANDLER_VALID, 
STACK_HANDLER, or REG_HANDLER fields of the associated procedure 
descriptor. You establish a handler by including the procedure value of the 
handler procedure in that field. (See Sections 3.4.1 and 3.4.4.)¢ 


In addition, the OpenVMS operating system on VAX and Alpha processors 
provides three statically allocated exception vectors for each access mode of a 
process. These vectors are available to declare condition handlers that take 
precedence over any handlers declared at the procedure level. The vectors are 
used, for example, to allow a debugger to monitor all exceptions and for the 
system to establish a last-chance handler. Because these handlers do not obey 
the procedure nesting rules, do not use them with modular code. Instead, use 
frame-based handlers. 


6.4.2 Reverting to the Caller’s Handling 


<> 
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On VAX systems, reverting to the caller’s handling deletes the condition handler 
associated with the current procedure activation. You do this by clearing the 
handler address in the stack frame. 


On VAX systems, the code to revert to the caller’s handling is as follows: 
CLRL 0(FP) 


On Alpha systems, there is no means to revert to a caller’s handler (unless a 
language provides emulation of dynamically specified handlers). ¢ 
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6.4.3 Signaling a Condition 
The signal operation is the method for indicating the occurrence of an exception 
condition. To initiate a signal and allow execution to continue after handling 
the condition, a program calls the LIB$SIGNAL procedure. To initiate a signal 
but not allow execution to continue at the point of initiation, a program calls the 
LIB$STOP procedure. The format of the LIB$SIGNAL and LIB$STOP calls are 
defined as follows: 


LIB$SIGNAL(condition-value, argn...) 
LIB$STOP(condition-value, argn...) 


ra 


Argument OpenVMS Usage Type Access Mechanism 
condition-value condition longword read by value 
argn integer quadword read by value 
Arguments: 


condition-value 
An OpenVMS condition value. 


argn 
Zero or more integer arguments that become the additional arguments of a signal 
argument vector (see Section 6.5.1.1) 


Function Value Returned: 
None. 


In both cases, the condition-value argument indicates the condition that 

is signaled. However, LIB$STOP sets the severity of the condition-value 
argument to be a severe error. The remaining arguments describe the details of 
the exception. These are the same arguments used to issue a system message. 


Unlike most calls, LIB$SIGNAL and LIB$STOP preserve all registers. Therefore, 
a debugger can insert a call to LIB$SIGNAL to display the entire state of the 
process at the time of the exception. Use of LIB$ routines also allows signals 

to be coded in an assembler language without changing the register usage. 

This feature of preserving all registers is useful for debugging checks and for 
gathering statistics. Hardware and system service exceptions behave like calls to 
LIB$SIGNAL. 


6.4.4 Signaling a Condition Using GENTRAP (Alpha Only) 


On Alpha systems, a GENTRAP PALcode instruction provides an efficient means 
for software to raise hardwarelike exceptions. This mechanism is used in low 
levels of the operating system or in the bootstrap sequence when only a limited 
execution environment is available. In a constrained environment, GENTRAP 
can be handled directly using the SCB vector by which the trap is reported. In 
a more complete environment, the GENTRAP parameter is transformed into 

a corresponding exception code and reported as a normal hardware exception. 
Because of this, low-level software can use this mechanism to report exceptions 
that are independent of the execution environment. Compiled code can also use 
the GENTRAP instruction to raise common generic exceptions more simply than 
by executing a complete LIB$SIGNAL procedure call. 
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The PALcode operation is defined as follows: 
GENTRAP ( expt_code ) 
The expt_code argument defines the code for the exception to be raised. 


If the expt_code value is one of the small negative values shown in Table 6-4, 
then that value is mapped to a corresponding OpenVMS exception code as shown. 
If the value is negative but not one of the values shown in Table 6—4, then SS$_ 
GENTRAP is raised with the unmapped value included in the exception record as 
the first and only qualifier value. Otherwise, a positive value is used directly to 
raise an exception using that value as the condition value. Note that there is no 
means to associate any parameters with an exception raised using GENTRAP. For 
more information on GENTRAP, see the Alpha Architecture Reference Manual.¢ 


Table 6—4 Exception Codes and Symbols for the Alpha GENTRAP Argument 


Exception 
Code Symbol Meaning 
—1 SS$_INTOVF Integer overflow 
—2 SS$_INTDIV Integer divide by zero 
-3 SS$_FLTOVF Floating overflow 
—4 SS$_FLTDIV Floating divide by zero 
5 SS$_FLTUND Floating underflow 
-6 SS$_FLTINV Floating invalid operand 
—7 SS$_FLTINE Floating inexact result 
8 SS$_DECOVF Decimal overflow 
-9 SS$_DECDIV Decimal divide by zero 
~10 SS$_DECINV Decimal invalid operand 
-11 SS$_ROPRAND Reserved operand 
~12 SS$_ASSERTERR Assertion error 
-13 SS$_NULPTRERR Null pointer error 
—14 SS$_STKOVF Stack overflow 
—15 SS$_STRLENERR String length error 
—16 SS$_SUBSTRERR Substring error 
17 SS$_RANGEERR Range error 
-18 SS$_SUBRNG Subscript range error 
-19 SS$_SUBRNG1 Subscript 1 range error 
—20 -SS$_SUBRNG2 Subscript 2 range error 
—21 SS$_SUBRNG8 Subscript 3 range error 
—22 SS$_SUBRNG4 Subscript 4 range error 
—23 SS$_SUBRNG5 Subscript 5 range error 
—24 SS$_SUBRNG6 Subscript 6 range error 
—25 SS$_SUBRNG7 Subscript 7 range error 
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6.4.5 Condition Handler Search 


The signal procedure examines the two exception vectors first, then examines 

a system-defined maximum number of previous stack frames, and, if necessary, 
examines the last-chance exception vector. The current and previous stack frames 
are found by using the frame pointer and chaining back through the stack frames 
using the saved context in each frame. The exception vectors have three address 
locations per access mode. 


As part of image startup, the system declares a default last-chance handler. This 
handler is used as a last resort when the normal handlers are not performing 
correctly. The debugger can replace the default system last-chance handler with 
its own. 


On Alpha systems, note that the default catchall handler in user mode can be a 
list of handlers and is not in conflict with this standard.¢ 





On both VAX and Alpha systems, in some frame before the call to the main 
program, the system establishes a default catchall condition handler that issues 
system messages. In a subsequent frame before the call to the main program, the 
system usually establishes a traceback handler. These system-supplied condition 
handlers use the condition-value argument to get the message and then use 
the remainder of the argument list to format and output the message through the 
SYS$PUTMSG system service. 


If the severity field of the condition-value argument (bits <2:0>) does not 
indicate a severe error (that is, a value of 4), these default condition handlers 
return with SS$_CONTINUE. If the severity is a severe error, these default 
handlers exit the program image with the condition value as the final image 
status. 


The stack search ends when the old frame address is 0 or is not accessible, or 
when a system-defined maximum number of frames have been examined. If a 
condition handler is not found, or if all handlers return with a SS$_RESIGNAL 
or SS$_RESIGNAL64, then the vectored last-chance handler is called. 


If a handler returns SS$_ CONTINUE or SS$_CONTINUE64, and LIB$STOP 
was not called, control returns to the signaler. Otherwise, LIB$STOP issues a 
message indicating that an attempt was made to continue from a noncontinuable 
exception and exits with the condition value as the final image status. 


Figure 6—2 lists all combinations of interaction between condition handler actions, 
default condition handlers, types of signals, and calls to signal or stop. In this 
figure, “Cannot Continue” indicates an error that results in the following message: 


IMPROPERLY HANDLED CONDITION, ATTEMPT TO CONTINUE FROM STOP. 
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Figure 6-2 Interaction Between Handlers and Default Handlers 
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6.5 Properties of Condition Handlers 


This section describes the properties of condition handlers for both VAX and 
Alpha environments. 


6.5.1 Condition Handler Parameters and Invocation 
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If a condition handler is found on a software-detected exception, the handler is 
called as follows: 


handler(signal_args, mechanism_args) 


Argument OpenVMS Usage Type Access Mechanism 
signal_args ' signal vector structure modify by reference 
mechanism_args mechanism ' structure modify by reference 
Arguments: 

signal_args 


A 32-bit signal argument vector (see Section 6.5.1.1) 

mechanism_args 

A mechanism argument vector (see Section 6.5.1. 2) 
Function Value Returned: 


One of the following status codes: SS$_CONTINUE, SS$_RESIGNAL, SS$_ 
CONTINUE64, SS$_RESIGNAL64. This value is used by the Condition Handling 
Facility to determine how to proceed next in processing the condition. (See 
Section 6.6.) 
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6.5.1.1 Signal Argument Vector 
There are two forms of signal argument vector (or signal vector for short): one 
for use with 32-bit addresses and one for use with 64-bit addresses. The two 
forms are compatible in that the forms can be distinguished dynamically at run 
time and, except for the size and offset of fields, are identical in content and 
interpretation. 


The 32-bit signal argument vectors are used on both OpenVMS VAX and 
OpenVMS Alpha systems. When used on OpenVMS Alpha, 32-bit signal 
argument vectors provide full compatibility with their use on OpenVMS VAX. 
The 64-bit signal argument vectors are used only on OpenVMS Alpha—they have 
no counterpart and are not recognized on OpenVMS VAX systems. — 


| Alpha | When a condition handler is called by the Condition Handling Facility (CHF) on 
Alpha, both forms of signal argument vector are available. The first argument 
is always a reference to a 32-bit form of signal argument vector. A handler 
that chooses to operate using the 64-bit form must obtain the address of the 
corresponding 64-bit signal argument vector from the CHF$PH_MCH_SIG64_ 
ADDR field of the mechanism argument vector (see Section 6.5.1.2).¢ 


Both forms of signal vector include a length field, a condition value, zero 

or more parameters that further qualify the condition value, and finally a 
processor program counter (PC) and program status (PS). For hardware-detected 
exceptions, the condition value indicates which exception was taken. The PC 
value gives the address of the instruction that caused the exception or the 
address of the next instruction, depending on whether the exception was a 

fault or a trap. For software-detected conditions, the condition value and any 
associated parameters are copies of the parameters to the call of LIB$SIGNAL or 
LIB$STOP that initiated exception handling, while the PC is the return address 
to the caller of that routine. 


Note that bits <2:0> of a condition value indicate severity and not what condition 
is being signaled. Therefore, a handler should examine only the condition 
identification, that is, condition value bits <27:3>, to determine the cause of 

the exception. The setting of severity bits <2:0> may vary from time to time even 
for the same condition. In fact, some handlers might only change the severity of 
a condition in the signal vector and resignal. 


Generally, a handler may validly modify any field of a signal argument vector 
except for the CHF$L_SIG_ARGS length field or, in the case of a 64-bit signal 
vector, the CHF$IS_SIGNAL64 field. In particular, a modified signal vector is 
passed to a subsequent handler if the current handler completes by resignaling. 
(If the length is modified, the modification is ignored; CHF restores the original 
length.) It is invalid for a handler to modify both forms of signal argument 
vector—the effect of doing so is undefined. 


The remainder of this section is organized as follows. First, the 32-bit form of 
signal argument vector is described. Second, the 64-bit form of signal argument 
is described. Finally, the relationship between the two forms is discussed. 


Figure 6-3 shows the format of the 32-bit form of signal argument vector. The 
CHF$L_SIG_ARGS longword contains the argument vector count, which is 

the number of remaining longwords in the vector. The CHF$L_SIG_NAME 
longword contains the condition value. Next are 0 or more longwords that contain 
additional parameters appropriate to the condition. The remaining two longwords 
contain the PC and PS values. 
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Figure 6-3 Signal Argument Vector—32-Bit Format 
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On VAX systems, the value used for the PS is the contents of the VAX processor 
status longword (PSL).¢ 


On Alpha systems, the value used for the PS is the low half of the Alpha processor 
status register. Furthermore, CHF$IS_SIG_ARGS and CHF$IS_SIG_NAME are 
aliases for CHF$L_SIG_ARGS and CHF$L_SIG_NAME, respectively. ¢ 


Figure 6-4 shows the format of the 64-bit form of signal argument vector. The 
address of this form of signal argument is available only from the CHF$PH_ 
MCH_SIG64_ADDR field of the mechanism argument vector (see Section 6.5.1.2). 
The CHF$L_SIG_ARGS field is a longword that contains the number of remaining 
quadwords in the vector (following the CHF$L_SIGNAL64 field). The CHF$L_ 
SIGNAL64 longword contains a special code named SS$_SIGNAL64 whose value 
is key to distinguishing between a 32-bit and 64-bit form of signal argument 
vector. The CHF$Q_ SIG_NAME quadword contains a sign-extended condition 
value. Next are zero or more quadwords that contain additional parameters 
appropriate to the condition. The remaining two quadwords contain the Alpha 
PC and PS values. 
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Figure 6—4 Signal Argument Vector—64-Bit Format 


31 0 
SS$SIGNAL64 


Condition value 






:CHF$L_SIG_ARGS 





:CHF$L_SIGNAL64 





:CHF$Q_SIG_NAME 





Additional arguments (or none) 





. ZK-7685A-GE 


At the time that a handler is called, the 32-bit and 64-bit alene argument vectors 
are closely related as follows: 


e The value of the length field in the 64-bit form (the number of quadwords 
following the CHF $L_SIGNAL64 field) is equal to the value of the length field 
‘in the 32-bit form (the number of longwords following the CHF$L_SIG_ARGS 
field). 


¢ The condition value, any related arguments, and the PC and PS values in the 
32-bit form are the same as the values in the 64-bit form truncated to 32 bits. 


Note that given a 64-bit signal vector, it is possible to create the corresponding 
32-bit signal vector by fetching the low-order longword of each quadword of the 
64-bit vector and packing the results together contiguously into a 32-bit vector; 
other than using the length, no interpretation of the contents is required. 


Given the address of a signal argument vector that might be either the 32-bit or 
64-bit form, either of the following equivalent tests may be used to distinguish 
which one is present: 


e Assuming a 32-bit form, compare the contents of the CHF$L_SIG_NAME field 
(equivalently CHF$L_SIGNAL64) with the value SS$_SIGNAL64. If equal, 
then the 64-bit form is present; otherwise, the 32-bit form is present. 


_¢ Assuming a 64-bit form, compare the contents of the CHF$L_SIGNAL64 field 
with the value SS$_SIGNAL64. If equal, then the 64-bit form is present; 
otherwise, the 32-bit form is present. ¢ 


6.5.1.2 Mechanism Argument Vector 
The mechanism argument vector for the argument mechanism_args contains 
information about the machine state when an exception occurs or when a 
condition is signaled. Therefore, the mechanism argument vector is highly 
specific to the underlying machine architecture. 
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On VAX systems, the mechanism format for the argument vectors is shown in 
Figure 6—5. The first longword contains the argument vector count, which is the 
number of remaining longwords in the vector. The frame longword contains the 
contents of the FP in the establisher’s context. If the restrictions described in 
Section 6.5.3.1 are met, the frame can be used as a base from which to access the 
local storage of the establisher. 


The depth longword is a positive count of the number of procedure-activation 
stack frames between the frame in which the exception occurred and the frame 
depth that established the handler being called. (For more information about 
depth, see Section 6.5.1.3.) 


The CHF$L_MCH_SAVRO and CHF$L_MCH_SAVR1 longwords save the state of 
the RO and R1 registers, respectively, at the time of the call to LIB$SIGNAL or 
LIB$STOP. If not modified by a handler during CHF processing, these values will 
become the values of those registers after completion of CHF processing (either by 
continuation or by unwinding). These two fields may be modified by a handler to 
establish different values to be used at CHF completion. Note that the contents 
of other registers are not available in the mechanism vector and can only be 
accessed by analysis of the stack. (See Section 6.7.1.) 


CHF$L_MCH_SAVRO and CHF$L_MCH_SAVR1 are the only fields of a VAX 
mechanism vector that can be validly modified by a handler. The effect of any 
other modification is undefined. 


Figure 6-5 VAX Mechanism Vector Format 
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If the VAX vector hardware or emulator option is in use, then for hardware- 
detected exceptions, the vector state is implicitly saved before any condition 
handler is entered and restored after the condition handler returns. (Save 

and restore is not required for exceptions initiated by calls to LIB$SIGNAL 

or LIB$STOP, because there can be no useful vector state at the time of such calls 
in accordance with the rules for vector register usage in Section 2.1.2.) Thus, a 
condition handler can make use of the system vector facilities in the same manner 
as mainline code. 


The VAX saved vector state is not directly available to a condition handler. 

A condition handler that needs to manipulate the vector state to carry out 
agreements with its callers can call the SYS$RESTORE_VP_STATE service. 
This service restores the saved state to the vector registers (whether hardware 
or emulated) and cancels any subsequent restore. The vector state can then be 
manipulated directly in the normal manner by means of vector instructions. (This 
service is normally of interest only during processing for an unwind condition.)¢ 
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On Alpha systems, the 64-bit-wide mechanism array is the argument mechanism 
in the handler call. The array shown in Figure 6-6 is defined by constant 
CHF$S_CHFDEF2 at a size of 360 bytes (45 quadwords). Table 6—5 lists and 
describes the fields. 


The CHF$IH_MCH_SAVRnn and CHF$FH_MCH_SAVFnn quadwords save the 
state of the nonpreserved general and floating registers, respectively, at the time 
of the call to LIB$SIGNAL or LIB$STOP. If not modified by a handler during 
CHF processing, these values will become the values of those registers after 
completion of CHF processing (either by continuation or by unwinding). These 
fields may be modified by a handler to establish different values to be used at 
CHF completion. 


The CHF$IH_MCH_SAVRnn and CHF$FH_MCH_SAVFnn fields are the only 
fields of an Alpha mechanism vector that can be validly modified by a handler. 
The effect of any other modification is undefined. (See also Section 6.7.2.) Note 
that the contents of the normally preserved registers are not available in the 
mechanism vector and can only be accessed by analysis of the stack. (See 
Section 6.7.1.) 
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Figure 6-6 Alpha Mechanism Vector Format 
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Table 6-5 Contents of the Alpha Argument Mechanism Array (MECH) 


Field Name 


CHF$IS_MCH_ARGS 


CHF$IS_MCH_FLAGS 


CHF$PH_MCH_FRAME 
CHF$IS_MCH_DEPTH 


CHF$IS_MCH_RESVD1 
CHF$PH_MCH_DADDR 


CHF$PH_MCH_ESF_ADDR 


CHF$PH_MCH_SIG_ADDR 


CHF$PH_MCH_SIG64_ 
ADDR 


CHF$IH_MCH_SAVRnn 


CHF$FH_MCH_SAVFnn 


Contents 


Count of quadwords in this array starting from the next quadword, 
CHF$IS_MCH_FRAME (not counting the first quadword that contains 
this longword). This value is always 44. 


Flag bits <31:0> for related argument-mechanism information defined as 
follows: 


CHF$V_FPREGS_VALID _ Bit 0. When set, the process has already 
performed a floating-point operation and 
the floating-point registers stored in this 


structure are valid. 


If this bit is clear, the process has not yet 
performed any floating-point operations and 
the values in the floating-point register slots 
in this structure are unpredictable. 


Contains the frame pointer in the procedure context of the establisher. 


Positive count of the number of procedure activation stack frames between 
the frame in which the exception occurred and the frame depth that 
established the handler being called (see Section 6.5.1.3). 


Reserved to Digital. 


Address of the handler data quadword if the exception handler data field 
is present (as indicated by PDSC$V_HANDLER_DATA_ VALID); otherwise, 
contains zero. 


Address of the exception stack frame (see the Alpha Architecture Reference 
Manual). 


Address of the 32-bit form of signal array. This array is a 32-bit wide 
(longword) array. This is the same array that is passed to a handler as the 
signal argument vector. 


Address of the 64-bit form of signal array. This array is a 64-bit wide 
(quadword) array. 


Contain copies of the saved integer registers at the time of the exception. 
The following registers are saved: RO, R1, and R16 through R28. Registers 
R2 through R15 are implicitly saved in the call chain. 


Contain copies of the saved floating-point registers at the time of the 
exception, or are unpredictable as described at field CHF$IS_MCH_ 
FLAGS. If the floating-point register fields are valid, the following registers 
are saved: FO, F1, and F10 through F30. Registers F2 through F9 are 
implicitly saved in the call chain. ¢ 


6.5.1.3. Mechanism Depth for Alpha and VAX Handler Arguments 
For Alpha and VAX argument mechanisms, the depth field has the value 0 for 
an exception that is handled by the procedure activation invoking the exception. 
The exception procedure contains the instruction that either causes the hardware 
exception or calls LIB$SIGNAL. The depth field of the argument mechanism has 
positive values for procedure activations calling the one having the exception, for 
example, 1 for the immediate caller. 
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If a system service gives an exception, the immediate caller of the service is 


notified at depth = 1. The depth field has a value of —2 when the condition 


handler is established by the primary exception vector, a value of —1 when it is 
established by the secondary vector, and a value of —3 when it is established by 
the last-chance vector. 


The Alpha mechanism depth may not be the same as the depth for the same 


circumstances on a VAX system if any of the following are present: 

¢ Condition dispatcher in the call chain 

¢ Jacket frames, if there are any translated routines in the call chain 
e Multiple active signals 


¢ Compiler use of no frame procedures or inline code expansion of calls 


6.5.2 System Default Condition Handlers 


If one of the default condition handlers established by the system is entered, the 
handler calls the SYS$PUTMSG system service to interpret the signal argument 
list and to output the indicated information or error message. See the description 
of SYS$PUTMSG in the OpenVMS System Services Reference Manual for the 
format of the signal argument list. 


6.5.3 Coordinating the Handler and Establisher 


This section describes the requirements for use of memory, exception 
synchronization, and continuation of the handler. 


6.5.3.1 Use of Memory 


Exceptions can be raised and unwind operations (which cause exception handlers 
to be called) can occur when the current value of one or more variables is in 
registers rather than in memory. Because of this, a handler, and any descendant 
procedure called directly or indirectly by a handler, must not access any variables 
except those explicitly passed to the procedure as arguments or those that exist 
in the normal scope of the procedure. 


This rule can be violated for specific memory locations only by agreement between 
the handler and all procedures that might access those memory locations. A 
handler that makes such agreements does not conform to this standard. 


6.5.3.2 Exception Synchronization (Alpha Only) 
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The Alpha hardware architecture allows instructions to complete in a different 
order than that in which they were issued, and for exceptions caused by an 
instruction to be raised after subsequently issued instructions have been 
completed. 


Because of this, the state of the machine when a hardware exception occurs _ 
cannot be assumed with the same precision as it can be assumed on conventional 
VAX machines unless such precision has been guaranteed by bounding the 
exception range with the appropriate insertion of TRAPB instructions. 


The rules for bounding the exception range follow: 


e Ifa procedure has an exception handler that does not simply reraise all 
arithmetic traps caused by code that is not contained directly within that 
procedure, the procedure must issue a TRAPB instruction before it establishes 
itself as the current procedure. 
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e Ifa procedure has an exception handler that does not simply reraise all 
arithmetic traps caused either by code that is not contained directly within 
that procedure or by any procedure that might have been called while that 
procedure was current, the procedure must issue a TRAPB instruction in the 
procedure epilogue while it is still the current procedure. 


¢ Ifa procedure has an exception handler that is sensitive to the invocation 
depth, the procedure must issue a TRAPB instruction immediately before and 
after any call. Furthermore, the handler must be able to recognize exception 
PC values that represent either epilogue code in called procedures or TRAPB 
instructions immediately after a call, and adjust the depth appropriately (see 
Section 3.7.5). 


These rules ensure that exceptions are detected in the intended context of the 
exception handler. 


These rules do not ensure that all exceptions are detected while the procedure 
within which the exception-causing instruction was issued is current. For 
example, if a procedure without an exception handler is called by a procedure 
that has an exception handler not sensitive to invocation depth, an exception 
detected while that called procedure is current may have been caused by an 
instruction issued while the caller was the current procedure. This means the 
frame, designated by the exception-handling information, is the frame that was 
current when the exception was detected, not necessarily the frame that was 
current when the exception-causing instruction was issued. ¢ | 


6.5.3.3 Continuation from Exceptions (Alpha Only) 


The Alpha architecture guarantees neither that instructions are completed in 
the same order in which they were fetched from memory nor that instruction 
execution is strictly sequential. Continuation is possible after some exceptions, 
but certain restrictions apply. 


By definition, software-raised general exceptions are synchronous with the 
instruction stream and can have a well-defined continuation point. Therefore, 

a handler can request continuation from a software-raised exception. However, 
since compiler-generated code typically relies on error-free execution of previously 
executed code, continuing from a software-raised exception might produce 
unpredictable results and unreliable behavior unless the handler has explicitly 
fixed the cause of the exception so that it is transparent to subsequent code. 


Hardware faults on Alpha processors follow the same rules as the strict 
interpretation of the conventional VAX rules. Loosely paraphrased, these rules 
state that if the offending exception is fixed, reexecution of the instruction (as 
determined from the supplied PC) will yield correct results. This does not imply 
that instructions following the faulting instruction have not been executed. 
Therefore, hardware faults can be viewed as similar to software-raised exceptions 
and can have well-defined continuation points. 


Arithmetic traps cannot be restarted because all the information required for 

a restart is not available. The most straightforward and reliable way in which 
software can guarantee the ability to continue from this type of exception is 

by placing appropriate TRAPB instructions in the code stream. Although this 
technique does allow continuation, it must be used with extreme caution because 
of the negative effect on application performance. ¢ 
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6.6 Returning from a Condition Handler 
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Condition handlers are invoked by the OpenVMS Condition Handling Facility 
(CHF). Therefore, the return from the condition handler is to the CHF. 


To continue from the instruction following the signal, the handler must return 
with a function value of either SS$¢_ CONTINUE or SS$_CONTINUE64 (both 
of which have bit <0> set). If, however, the condition is signaled with a call to 
LIB$STOP, the image exits. To resignal the condition, the condition handler 
returns with a function value of either SS$_RESIGNAL or SS$_RESIGNAL64 
(both of which have the bit <0> clear). 


The difference between SS$_CONTINUE and SS$_CONTINUE64, and similarly 
between SS$_RESIGNAL and SS$_RESIGNAL64, is of significance only if the 
handler has made an alteration to the signal vector that is intended to be taken 


.into account by the CHF. When SS$_CONTINUE or SS$_RESIGNAL is returned, 


then any modification to the 32-bit signal vector is propagated (in sign-extended 
form) to the corresponding position in the 64-bit vector. When SS$_CONTINUE64 
or SS$_RESIGNAL64 is returned, any modification in the 64-bit signal vector is 
propagated (in truncated form) to the corresponding position in the 32-bit vector. 
If no modification has been made, then the two forms of continuation or resignal 
are equivalent. 


The algorithm for detecting change is as follows: 


¢ For SS$_CONTINUE64 and SS$_RESIGNAL64, the 32-bit signal vector is 
simply derived again from the 64-bit signal vector. In particular, no hidden 
copy of the 64-bit signal vector is kept. It is not necessary to determine if 
there was a change or not—if there was, it is properly reflected in the 32-bit 
vector. 


e For SS$_CONTINUE and SS$_RESIGNAL, let SIGVEC32[I] and 
SIGVEC64[I] be corresponding entries in the two vectors, for I from 1 to 
length. (Recall that the length[s] cannot be changed.) For each entry, do the 
following: . 


if SIGVEC32[I] /= SIGVEC64[I]<0,32> 
then 
SIGVEC64[I] = sign-extend(SIGVEC32[I]) 


That is, if the 32-bit entry is still the same as the low-order 32 bits of the 
64-bit entry, then it did not change and thus the 64-bit entry is not changed. 
Otherwise, update the 64-bit entry with the sign-extended contents of the 
32-bit entry. 


To alter the severity of the signal, the handler modifies the low-order three bits 
of the condition value longword in the signal_args vector and resignals. If 
the condition handler wants to alter the defined control bits of the signal, the 
handler modifies bits <31:28> of the condition value and resignals. To unwind, 
the handler calls SYS$UNWIND and then returns. In this case, the handler 
function value is ignored. 
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6.7 Request to Unwind from a Signal 


To unwind, the handler or any procedure that it calls can make a call to 
SYS$UNWIND. The format is as follows: 


SYS$UNWIND(depadr, new_PC) 


Argument OpenVMS Usage Type Access Mechanism 


depadr integer longword read by reference 
new_PC address longword read by reference 
Arguments: 

depadr 

Optional number of presignal frames (depth) to be removed. 

new_PC 

Optional address of the location to receive control after the unwind operation is 

completed. 


Function Value Returned: 
Success or failure status (see below). 


The depadr argument specifies the address of the longword that contains the 
number of presignal frames (depth) to be removed. The deepest procedure 
invocation whose frame is not removed is called the target invocation of the 
unwind. If that number is less than or equal to 0, nothing is to be unwound. The 
default (address = 0) is to return to the caller of the procedure that established 
the handler that issued the $UNWIND service. To unwind to the establisher, 
specify the depth from the call to the handler, which can be found in the CHF$IS_ 
MCH_DEPTH field of the Mechanism Array. When the handler is at depth 0, 

it can achieve the equivalent of an unwind operation to an arbitrary place in 

its establisher by altering the PC in its signal_args vector and returning with 
SS$_CONTINUE, or SS$_CONTINUE64 if the 64-bit signal vector is altered, 
instead of performing an unwind. 


The new_PC argument specifies the location to receive control when the 
unwinding operation is complete. The default is to continue at the instruction 
following the call to the last procedure activation that is removed from the stack. 


The function value success either is a standard success code (SS$_ NORMAL) or 
it indicates failure with one of the following return status condition values: 


¢ No signal active (SS$_NOSIGNAL) 
e Already unwinding (SS$_UNWINDING) . 
¢ Insufficient frames for depth (SS$_INSFRAME) 


If SYS$UNWIND is invoked by a handler that has already invoked 
SYS$UNWIND, then the effect of the second invocation is undefined. 


The unwinding operation occurs when the handler returns to the CHF. Unwinding 
is done by scanning back through the stack and calling each handler associated 
with a frame. The handler is called with the exception SS$_UNWIND to perform 
any application-specific cleanup. If the depth specified includes unwinding the 
establisher’s frame, the current handler is recalled with this unwind exception. 
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| Alpha When the target invocation is reached on Alpha systems, unwind completion 
depends on the PDSC$V_TARGET_INVO flag of the associated procedure 
descriptor. If that flag is set to 1, then the handler for that procedure invocation 
is called; otherwise, no handler is called. Control then resumes in the target 
invocation. ¢ 


The call to the handler takes the same form as described in Section 6.5.1 with the 
following values: 


¢ signal_args: for a handler for a procedure other than the target invocation 
of the unwind—an argument count (CHF$L_SIG_ARGS) of 1 and a condition 
value (CHF $L_SIG_NAME) of SS$_UNWIND. 


| Alpha | For a handler on Alpha systems for a procedure that is the target invocation 
of the unwind—an argument count (CHF$L_SIG_ARGS) of 2 and two 
condition values consisting of SS$_UNWIND followed by SS$_TARGET_ 
UNWIND. ¢ 


¢ mechanism_args: same as for the original call except for a depth of 0 (that 
is, unwinding self) and any other changes made by prior handlers. 


After each handler is called, the stack is logically cut back to the previous frame. 


| Alpha | On Alpha systems, the stack is not actually cut back until after the last handler 
is called. ¢ 


The exception vectors are not checked because they are not being removed. Any 
function value from the handler is ignored. 


To specify the value of the top-level function being unwound, the handler should 
modify the appropriate saved register locations in the mechanism_args vector. 
They are restored from the mechanism_args vector at the end of the unwind. 


Depending on the arguments to SYS$UNWIND, the unwinding operation is 
terminated as follows: 


SYS$UNWIND(0,0) Unwind to the establisher’s caller. 

SYS$UNWIND(depth,0) Unwind to the establisher at the point of the call 
that resulted in the exception. 

SYS$UNWIND (depth, location) Unwind to the specified procedure activation and 


transfer to a specified location. 


The only recommended values for depth are the default (address of 0), which 
unwinds to the caller of the establisher, and the value of depth taken from the 
mechanism vector, which unwinds to the establisher. Other values depend on 
implementation details that can change at any time. 


You can call SYS$UNWIND whether the condition was a software exception 
signaled by calling LIB$SIGNAL or LIB$STOP or was a hardware exception. 
Calling SYS$UNWIND is the only way to continue execution after a call to 
LIB$STOP. 


6.7.1 Signaler’s Registers 


Because the handler is called and can in turn call routines, the actual register 
values in use at the time of the signal or exception can be scattered on the stack. 
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On VAX systems, to find registers R2 through FP, a scan of stack frames must 
be performed starting with the current frame and ending with the call to the 
handler. During the scan, the last frame found to save a register contains that 
register’s contents at the time of the exception. If no frame saved the register, 
the register is still active in the current procedure. The frame of the call to the 
handler can be identified by the return address of SYS$CALL_HANDL+4. In this 
case, the registers are in the following states: 


RO, R1 In mechanism_args 

R2-11 Last frame saving it 

AP Old AP of SYS$CALL_HANDL+4 frame 
FP Old FP of SYS$¢CALL_HANDL+4 frame 
SP Equal to end of signal_args vector+4 


PC, PSL At end of signal_args vector ¢ 


On Alpha systems, to find the contents of the registers, use the invocation context 
routines described in Section 3.6.3.¢ 


6.7.2 Unwind Completion 


<i> 





On VAX systems, the values that exist in RO and R1 when the unwind completes 
are the values passed implicitly to the unwinder in the mechanism array (see 
Section 6.5.1.2). If desired, these values can be modified by an exception handler 
before the unwind is initiated. ¢ 


On Alpha systems, the values that exist in RO, R1, FO, and F1 when the unwind 
completes are the values passed implicitly to the unwinder in the mechanism 
array (see Section 6.5.1.2). If desired, these values can be modified by an 
exception handler before the unwind is initiated. Note that, unlike VAX systems, 
an Alpha system does not use R1 for returning any type of return values. ¢ 


6.8 GOTO Unwind Operations (Alpha Only) 





A GOTO unwind is a transfer of control that leaves one procedure invocation 
and continues execution in a prior, currently active procedure invocation. 
Modular and reliable support of the nonlocal GOTO requires procedure 
invocations that are terminated have an opportunity to clean up in an orderly 
way (just like a procedure that is terminated as a result of an unwind from a 
condition handler). 


Performing a GOTO unwind operation in a thread causes a transfer of control 
from the location at which the GOTO unwind operation is initiated to a target 
location in a target invocation. This transfer of control also results in the 
termination of all procedure invocations, including the invocation in which the 
unwind request was initiated, up to the target procedure invocation. Thread 
execution then continues at the target location. 


Before control is transferred to the unwind target location, the unwind support 
code invokes all frame-based handlers that were established by procedure 
invocations being terminated. These handlers are invoked with an indication of 
an unwind in progress. This gives each procedure invocation being terminated 
the chance to perform cleanup processing before its context is lost. 


When the target invocation is reached, unwind completion depends on the 
PDSC$V_TARGET_INVO flag of the associated procedure descriptor. If that flag 
is set to 1, then the handler for that procedure invocation is called; otherwise, no 
handler is called. 
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After all the relevant frame-based handlers have been called and the appropriate 
frames have been removed from existence, the target invocation’s saved context is 
restored and execution is resumed at the specified location. 


A GOTO unwind procedure can be initiated while an exception is active (from 


-within a condition handler) or while no exception is active. If the GOTO unwind 


transfers control out of an exception handler (resulting in the termination of 
current handler invocation), it also terminates handling of the corresponding 
condition (like SYS$UNWIND). 


A GOTO unwind operation in which a target invocation is not specified is called 
an exit unwind. An exit unwind is just like a GOTO unwind except that 
every procedure invocation in the currently executing thread is terminated. An 
exit unwind is the only standard way to terminate execution of the currently 
executing thread (other than a normal return from the topmost procedure of the 
thread). 


A thread can initiate a GOTO unwind or an exit unwind operation by calling a 
system service routine. This routine is defined as follows: 


SYS$GOTO_UNWIND(target_invo, target_pc, new_RO, new_R1) 


Argument OpenVMS Usage Type Access Mechanism 
target_invo invo_handle longword (unsigned) read by reference 
target_pc address longword (unsigned) read by reference 
new_R0 quadword_unsigned quadword (unsigned) read by reference 
new_R1 quadword_unsigned quadword (unsigned) read by reference 
Arguments: 


target_invo 
Address of a location that contains a handle for the target invocation. 


If omitted or the address of the handle is zero, then an exit unwind is initiated. 


target_pc 
Address of a location that contains the address at which execution should continue in 
the target invocation. 


If omitted or if the address is zero, then execution resumes at the location specified by 
the return address for the call frame of the target procedure invocation. 


If the target_invo argument is omitted or is zero, then this argument is ignored. In 
this case, a system-defined target PC is assumed. 


new_RO 

Address of a location that contains the value to place in the saved RO location of the 
mechanism argument vector. The contents of this location are then loaded into RO at 
the time that execution continues in the target invocation. 


If this argument is omitted, then the contents of the processor RO register at the time 
of the call to SYS$GOTO_UNWIND are used. 


new_Rl 

Address of a location that contains the value to place in the saved R1 location of the 
mechanism argument vector. The contents of this location are then loaded into R1 at 
the time that execution continues in the target invocation. 


If this argument is omitted, then the contents of R1 at the time of the call to 
SYS$GOTO_UNWIND are used. 
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Condition Value Returned: 


'SS$_ACCVIO 
An invalid address was given. 


When a GOTO unwind is initiated, control usually never returns to the point 
at which the unwind was initiated. Control returns with an error status only 
if a GOTO unwind cannot be started. If SYS$GOTO_UNWIND is invoked by 
a handler that has already invoked SYS$UNWIND, then the effect of calling 
SYS$GOTO_UNWIND is undefined. 


6.8.1 Handler Invocation During a GOTO Unwind 


When an unwind operation takes place, all frame-based exception handlers are 
invoked that were established by any procedure invocation being terminated. In 
addition, the handler for the target procedure invocation is called if the PDSC$V_ 
TARGET_INVO flag is set in the corresponding procedure descriptor (see Sections 
3.4.2 and 3.4.5.) These handlers are invoked in the reverse order from which they 
were established. . 


Since primary, last-chance handlers and the system catchall handler are not 
associated with a normal procedure invocation, these handlers are never invoked 
during an unwind (but they are invoked if an exception is raised during the 
unwind operation). 


For a GOTO or exit unwind procedure, each handler that is invoked is called with 
two arguments as follows: 


handler (signal_args, mechanism_args) 


Argument OpenVMS Usage Type Access Mechanism 
signal_args ~ signal vector structure modify by reference 
mechanism_args mechanism vector structure modify by reference 
Arguments: 

signal_args 


Argument count of 2, followed by a condition value of SS$_UNWIND, followed by: 
e SS$_EXIT_UNWIND when no target invocation is specified 


e SS$ _GOTO_UNWIND when a target invocation is specified but not for that target 
invocation 


e SS$_TARGET_GOTO_UNWIND when a target invocation is specified and the 
handler for that target invocation is called 


mechanism_args 
Mechanism argument corresponding to the frame being unwound, as defined in 
Section 6.5.1.2. 


For information about signal argument and mechanism argument vectors, see 
Sections 6.5.1.1 and 6.5.1.2. 
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6.8.2 Unwind Completion | 
When an unwind completes, the following conditions are true: 


e The target procedure invocation is the most current invocation in the 
procedure invocation chain. 


e The environment of the target invocation is restored to the state when that 
invocation was last current, except for the contents of all scratch registers. 


e RO and R1 contain the respective values, if any, which were passed by the 
routine that invoked the unwind. 


e Execution continues at the target location. ¢ 


6.9 Multiple Active Signals 


A signal is said to be active until the signaler gets control again or is unwound. 
A signal can occur while a condition handler or a procedure it has called is 

- executing in response to a previous signal. For example, procedures A, B, and C 
establish condition handlers Ah, Bh, and Ch. If A calls B and B calls C, which 
signals S, and Ch resignals, then Bh gets control. 


If Bh calls procedure X, and X calls procedure Y, and Y signals T, the stack is as 
follows: 


<Signal T> 
¥ 
X 
Bh 
<Signal S> 
C 


B 
A 


Which was programmed: 
A 


— —X——_nnnr Bh 
Cc X 


<Signal S> . Y 


<Signal T> 


ZK-1884-GE 


The handlers are searched for in the following order: Yh, Xh, Bhh, Ah. Bh is 
not called again because it is not appropriate to assume that a routine is able to 
be its own handler. However, Bh can establish itself or another procedure as its 
handler (Bhh). 


qs> On VAX systems, Ch is not checked or called because it is a structural descendant 
of B.¢ 
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| Alpha | On Alpha systems, the search does check handlers Ch and Bh between calling 
Bhh and Ah. These handlers will be reinvoked only if enabled by the HANDLER_ 
REINVOCABLE flag of the establisher’s procedure descriptor (see Sections 3.4.1 
and 3.4.4).¢ . 


For both Alpha and VAX systems, the following algorithm is used on the second 
and subsequent signals that occur before the handler for the original signal 
returns to the Condition Handling Facility. The primary and secondary exception 
vectors are checked. Then, however, the search backward in the process stack is 
modified. On a VAX processor, the stack frames traversed in the first search are 
skipped in effect during the second search, while on an Alpha processor, the stack 
frames are skipped unless they explicitly enable handler reinvocation. Thus, 

the stack frame preceding the first condition handler, up to and including the 
frame of the procedure that has established the handler, is skipped. In the VAX 
environment, frames that are skipped are not counted in the depth. In the Alpha 
environment, all frames are counted in the depth. 


For example, the stack frames traversed in the first and second searches are 
skipped in a third search. Note that if a condition handler signals, it is not 
automatically invoked recursively. However, if a handler itself establishes a 
handler, the second handler is invoked. Thus, a recursive condition handler 
should start by establishing itself. Any procedures invoked by the handler are 
treated in the normal way; that is, exception signaling follows the stack up to the 
condition handler. 


If an unwind operation is requested while multiple signals are active, all the 
intermediate handlers are called for the operation. For example, in the preceding 
diagram, if Ah specifies unwinding to A, the following handlers are called for the 
unwind: Yh, Xh, Bhh, Ch, and Bh. 


For proper hierarchical operation, an exception that occurs during execution 
of a condition handler established in an exception vector should be handled by 
that handler rather than propagating up the activation stack. To prevent such 
propagation, the vectored condition handler should establish a handler in its 
stack frame to handle all exceptions. 


6.10 Multiple Active Unwind Operations 


During an unwind operation (resulting from either SYS$GOTO_ UNWIND 

or SYS$SUNWIND), another unwind operation may be initiated (using either 
SYS$GOTO_UNWIND or SYS$UNWIND). This can occur, for example, if a 
handler that is invoked for the original unwind initiates another unwind, or if an 
exception is raised in the context of such a handler and a handler invoked for that 
exception initiates another unwind operation. Note, however, that SYSSUNWIND 
cannot be called from a handler that is invoked as part of an unwind (see 
Section 6.7), but it can be called from a handler for a nested exception. 


An unwind that is initiated while a previous unwind is active is either a nested 
unwind or an overlapping unwind. 


A nested unwind is an unwind that is initiated while a previous unwind is 
active and whose target invocation in the procedure invocation chain is not a 
predecessor of the most current active unwind handler. A nested unwind does 
not terminate any procedure invocation that would have been terminated by the 
previously active unwind. 
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When a nested unwind is initiated, no special rules apply. The nested unwind 
operation proceeds as a normal unwind operation, and when execution resumes 
at the target location of the nested unwind, the nested unwind is complete and 
the previous unwind is once again the most current unwind operation. 


An overlapping unwind is an unwind that is initiated while a previous unwind 
is active and whose target invocation in the procedure invocation chain is a 
predecessor of the most current active unwind handler. An overlapping unwind 
terminates one or more procedure invocations that would have been terminated. 
by the previously active unwind. 


An overlapping unwind is detected when the most current active unwind handler 
is terminated. This detection of an overlapping unwind is termed an unwind 
collision. 


When a GOTO unwind collides with a GOTO unwind, the later unwind 
supersedes the earlier unwind, which is abandoned. The later unwind then 
continues from the point of the collision. 


The result of any other collision is undefined. 
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Active procedure, 3-29 
Addresses 
for OpenVMS Alpha, 1-4 
for OpenVMS VAX, 1-4 
Address representation, 3-3 
AI (argument information) 
format, 3-38 
register, 3-38 
Aligned record layout, 3-58 
Argument data types, 4-1 


Argument descriptors 


See DSCs 
Argument home area, 3-12 
Argument information 
See AI 
Argument items 
for Alpha, 3-48 
Argument lists, 3-12, 3-37 
definition, 1—4 
evaluation, 2-5 
for Alpha, 3-49 
format, 2—4 
for VAX, 2-3 
interpretating, 2—4 
Argument mechanisms, 6—13 
Argument order 
Alpha evaluation, 3-53 
Arguments, 3-12, 3-49 
passed in memory, 3-9, 3-12 
Argument vectors 
mechanism, 6-15 
Array descriptors, 5-7 
Asynchronous software interrupts 
definition, 1-4 
Atomic data types, 4-1 


Base register architecture, 3-39 
BASIC file array descriptors, 5-33 
Bits 

unused in passed data, 3-50 
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Bound procedure descriptors, 3—42 
Bound procedures, 3-42 
definition, 1-4 
environment value, 3-45 
Bound procedure values, 3-3, 3-44 
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Call chain, 3-29 
how to walk, 3-33 
transfer of control, 3-37 
Call conventions 
invocation and return, 3-37 
Call frames 
definition, 1-4 
Calling sequence, 2-3 
argument list, 2-3 
Calling standard 
architectural level, 1-2 
goals, 1-2, 1-3 
terms, 1-4 
Calls 
with computed addresses, 3-41 
Call tracing, 3-30 
CHF 
See Condition Handling Facility (CHF) 
Compression text descriptors, 5-33 
Computed calls, 3-41 
Condition handlers, 6-6 
coordinating with establisher, 6-20 
default, 6—20 
definition, 1—4 
deleting, 6-8 
establishing, 6-8 
exceptions, 6—6 
memory use, 6—20 
multiple active signals, 6-28 
operations, 6-7 
options, 6—7 
parameters and invocation, 6—12 
properties, 6-12 
register values, 6—24 
reinvokable, 6—28 
request to unwind, 6-23 
returning from, 6—22 
search, 6-11 
stack usage, 6-7 
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Condition handling 
procedure exceptions, 6-1 
standards, 6—1 
vector processor, 6-16 
Condition Handling Facility (CHF), 6-6, 6-7 
Conditions 
from called procedures, 6-1 
Condition values 
condition identification, 6-3 
control, 6-3 
definition, 1-4 
description, 6-1 
facility, 6-3 
format, 6-1 
interpreting severity codes, 6-4 
message number, 6-3 
registers use, 2-1 
severity codes, 6-3 
symbols, 6-3 
use, 6—5 
Conventions 
OpenVMS Alpha, 3-1 
OpenVMS VAX, 2-1 
Current procedure, 3-29 
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Data alignment, 3-56 
Data passing 
for Alpha systems, 3-48 
unused bits, 3-50 
Data types 
atomic 
DSC$K_DTYPE_B, 4-2 
DSC$K_DTYPE_BU, 4-2 
DSC$K_DTYPE_D, 4-2 
DSC$K_DTYPE_DC, 4-3 
DSC$K_DTYPE_F, 4-2 
DSC$K_DTYPE_FC, 4-2 
DSC$K_DTYPE_FS, 4-3 
DSC$K_DTYPE_FSC, 4-3 
DSC$K_DTYPE_FT, 4-3 
DSC$K_DTYPE_FTC, 4-3 
DSC$K_DTYPE_FX, 4-3 
DSC$K_DTYPE_FXC, 4-3 
DSC$K_DTYPE_G, 4-2 
DSC$K_DTYPE_GC, 4-3 
DSC$K_DTYPE_H, 4-2 
DSC$K_DTYPE_HC, 4-3 
DSC$K_DTYPE_L, 4-2 
DSC$K_DTYPE_LU, 4-2 
DSC$K_DTYPE_O, 4-2 
DSC$K_DTYPE_OU, 4-2 
DSC$K_DTYPE_Q, 4-2 
DSC$K_DTYPE_QU, 4-2 
DSC$K_DTYPE_W, 4-2 
DSC$K_DTYPE_WU, 4-2 
DSC$K_DTYPE_Z, 4-2 
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codes 
facility specific, 4-6 
reserved, 4—5 
miscellaneous 
DSC$K_DTYPE_ADT, 4-5 
DSC$K_DTYPE_BLV, 4-5 
DSC$K_DTYPE_BPV, 4-5 
DSC$K_DTYPE_DSC, 4-5 
DSC$K_DTYPE_ZEM, 4-5 
DSC$K_DTYPE_ZI, 4-5 
string 
DSC$K_DTYPE_NL, 4-4 
DSC$K_DTYPE_NLO, 44 
DSC$K_DTYPE_NR, 44 
DSC$K_DTYPE_NRO, 44 
DSC$K_DTYPE_NU, 4-4 
DSC$K_DTYPE_NZ, 4-4 
DSC$K_DTYPE_P, 44 
DSC$K_DTYPE_T, 4-4 
DSC$K_DTYPE_V, 4-4 
DSC$K_DTYPE_VT, 4~—4, 4-6 
DSC$K_DTYPE_VU, 4-4 
varying character string, 4—6 
DSC$K_DTYPE_VT, 4-6 
Decimal string descriptors, 5-13 
Default condition handlers, 6-20 
Default procedure signature, 3-28 
Definition of terms, 1-4 
Descriptors 


See also DSCs and PDSCs 

Alpha argument item, 3—48 

arrays, 5-7 

BASIC file array, 5-33 

class codes, 5-33 

compression text, 5-33 

decimal strings, 5-13 

definition, 1-4 

dynamic strings, 5-6 

facility-specific class codes, 5-33 

fixed length, 5-5 

formats 
DSC$A_POINTER, 5-4 
DSC$B_CLASS, 5-4 
DSC$B_DTYPE, 5-4 
DSC$K_CLASS_A, 5-7 
DSC$K_CLASS_BFA, 5-33 
DSC$K_CLASS_CT, 5-33 
DSC$K_CLASS_D, 5-6 
DSC$K_CLASS_J, 5-33 
DSC$K_CLASS_JI, 5-33 
DSC$K_CLASS_NCA, 5-15 
DSC$K_CLASS_P, 5-12 
DSC$K_CLASS_PI, 5-33 
DSC$K_CLASS_S, 5-5 
DSC$K_CLASS_SB, 5-29 
DSC$K_CLASS_SD, 5-18 
DSC$K_CLASS_UBA, 5-25 
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formats (cont'd) 
DSC$K_CLASS_UBS, 5-24 
DSC$K_CLASS_UBSB, 5-31 
DSC$K_CLASS_V, 5-33 
DSC$K_CLASS_VS, 5-19 
DSC$K_CLASS_VSA, 5-21 
DSC$W_LENGTH, 5-4 
DSC64$B_CLASS, 5-4 
DSC64$B_DTYPE, 5-4 
DSC64$L_MBMO, 5-4, 5-6, 5-7, 5-10, 
5-18, 5-14, 5-18, 5-20, 5-24 
DSC64$PQ_POINTER, 5-4 
DSC64$Q_LENGTH, 5-4 
DSC64$W_MBO, 5-4, 5-5, 5-7, 5-10, 
5-18, 5-14, 5-18, 5-20, 5-24 
prototype, 5-2 
label, 5-33 
noncontiguous arrays, 5-15 
obsolete class codes, 5-33 
procedure argument, 5-12 
reserved class codes, 5-33 
strings with bounds, 5-29 
unaligned bit arrays, 5-25 
unaligned bit strings, 5-24 — 
unaligned bit strings with bounds, 5-31 
variable buffer, 5-33 
varying string arrays, 5-21 
varying strings, 5-19 
DSCs 
argument descriptors, 5-1 to 5-33 
procedure descriptors, 5-12 
Dynamic string descriptor, 5-6 
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Entry code sequences, 3—45 
example for register frame procedures, 3—47 
example for stack frame procedures, 3-46 
Environment value, 3-45 
Exception conditions, 6—1 
definition, 1-4 
handler, 6-6 
indicating, 6-9 
signaling, 6-9 
Exceptions 
continuation from, 6-21 
synchronization, 6-20 
Exit code sequences, 3-47 
example for register frame procedures, 3-48 
example for stack frame procedures, 3-48 
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Facility-specific data type codes, 4-6 
Facility-specific descriptor class codes, 5-33 


Fixed length 

returned to stack, 2-8 
Fixed-length descriptor, 5-5 
Fixed-size stack frames, 3-9 
Fixed temporary locations, 3-12 
Floating-point register usage, 3-2 
Flow control, 3-3 
Full function, 3-4 
Function 

definition, 1-5 
Function result, 3-38 
Function value returns 

by descriptor, 3—55 

by immediate value, 3-54 

by reference, 3-54 

dynamic text, 3-55 

in registers, 2-6 

object created by called routine, 3-55 

object created by calling routine, 3-55 

registers, 2-1 

to stack, 2~7, 2-8 
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GENTRAP instruction, 6—9 

GOTO unwinds, 6-25 
nonlocal, 6—25 

Guard pages, 3-60 

Guard regions, 3-60 
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Handler invocations 
during unwind, 6—27 

Hardware exceptions, 6-1 
definition, 1-5 

High-level languages 
argument evaluation, 2-5 
argument transmission, 2-5 
mapped into argument lists, 2-5 


ICBs (invocation context blocks), 3-31 
Immediate value 
Alpha argument item, 3-48 
definition, 1-5 
large, 3-52 
Inline code, 3-62 
Integer register usage, 3-1 
Invocation context 
access routines, 3-34 
functions, 3-34 
obtaining handle, 3-35 
updating, 3-36 
Invocation context blocks 
See ICBs 
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Invocation handles, 3-30 
creating, 3-33 
encoding, 3-30 
format for procedure, 3-30 
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Label descriptors, 5-33 
Language extensions, 2-5 
Language-support procedure, 1-5 
Large immediate value 

Alpha, 3-52 
LIB$GET_CURR_INVO_CONTEXT routine, 3-34 
LIB$GET_INVO_CONTEXT routine, 3-34 
LIB$GET_INVO_HANDLE routine, 3-35 
LIB$GET_PREV_INVO_CONTEXT routine, 3-35 
LIB$GET_PREV_INVO_HANDLE routine, 3-36 
LIB$PUT_INVO_REGISTERS routine, 3-36 
LIB$SIGNAL routine © 

signaling, 6—9, 6-13 
LIB$STOP routine 

using, 6-9, 6-11, 6-13 
Library procedures, 1-5 
Lightweight procedures 

Alpha requirements, 3-14 
Linkage pair blocks 

See LKPs 
Linkage pointers, 3-39 
Linkage sections, 3-39 
LKPs (linkage pair blocks), 3-40 
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Miscellaneous data types, 4—4 
Multiple active signals, 6—28 
Multithreaded execution environments, 3-59 
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Natural alignment 
definition, 1-5 
Nested unwind, 6-29 
New stack region, 3-60 
Noncontiguous array descriptors, 5-15 
Null frame procedures, 3-20 
descriptors, 3-20 
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Obsolete descriptor class codes, 5-33 
Overlapping unwind, 6-30 
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Passing mechanisms 
descriptor 
definition, 1-4 
immediate value 
definition, 1-5 - 
language extensions, 2-5 
reference 
definition, 1-5 
PDSCs (procedure descriptors), 3-3 
for bound procedures, 3—42 
for null frame procedures, 3-20 
for register frame procedures, 3-15 
for stack frame procedures, 3-5 
Procedure call 
chain, 3-29 
tracing, 3-30 
Procedure descriptors 
See PDSCs for Alpha or DSCs for VAX and 
Alpha 
Procedure invocation, 3—29 
handle, 3-30 
Procedures, 3-3 
definition, 1-5 
language support, 1-5 
library, 1-5 
without frames, 3-20 
Procedure signature information blocks 
See PSIGs 
Procedure signatures, 3—22 
default, 3-28 
Procedure types, 3-3 
Procedure values, 1-5, 3-37 
bound, 3-3, 3-44 
definition, 3-3 
examining, 3-41 
Process 
definition, 1-5 
PSIGs (procedure signature information blocks), 
3-22 
field conversions, 3-25 
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Receiving data 
Alpha, 3-53 
Record layout 
Alpha, 3-57 
VAX compatible, 3-59 
Reference 
definition, 1-5 
Reference argument item 
for Alpha, 3-48 


Register frame procedures, 3-14 
descriptors, 3-15 
Registers 
Alpha usage, 3-1 
floating point usage, 3-2 
for returns, 2-1 
integer usage, 3-1: 
scalar, 2-1 
VAX usage, 2-1 - 
vector, 2-2 
Register save area 
See RSA 
Request to unwind, 6-23 
Reserved data type codes, 4-5 
Reserved descriptor class codes, 5-33 
Reserve region, 3-60 
Returning data 
Alpha, 3-53 
Returning from condition handlers, 6-22 
Returning function value 
fixed length to stack, 2-8 


to stack, 2-7 
varying string to stack, 2-8 
Returns 


address, 3-37 
condition value, 6-1 
function value, 2-6 
Revert to caller’s handling, 6—8 
RSA (register save area) 
layout, 3-12, 3-13 
stack frames, 3-12 
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Scalars 

processor synchronization, 2-8 

register usage, 2-1 
Sending data, 3-52 

Alpha mechanisms, 3-52 

argument order evaluation, 3-53 
Severity codes, 6-3 

handling, 6—4 

interpreting, 6—4 

meanings, 6-4 

symbols, 6-4 
Signal 

definition, 1-6 
Signal argument vectors, 6—13 fi 
Signaler’s register, 6-24 
Signaling conditions, 6-9 

with GENTRAP, 6-9 

with LIB$SIGNAL, 6-9 
Signature information, 3-22 
Simple procedure, 3-44 
Stack frames 

fixed size, 3-9 

format, 3-8 


Stack frames (cont'd) 
procedure descriptors, 3-5 
procedures, 3-4 
register save area, 3-12 
variable size, 3-10 

Stack guard region 
multithreads, 3-60 

Stack limit checking 
explicit, 3-62 
implicit, 3-61 
methods, 3-60 
multithreads, 3-60 

Stack overflow 
handling, 3-62 
multithreads, 3—60 

Stack region, 3-60 

Stack reserve region 
checking, 3-62 
multithreads, 3-60 

Stack return 
mechanism, 3-56 
values to top, 2-7 

Stack temporary area, 3-11 

Stack usage, 3-39, 6-7 
for Alpha systems, 3-8 
for VAX, 2-2 

Standard calls 
definition, 1-6 

Standard-conforming procedures 
definition, 1-6 

Static data, 3-56 

Static data alignment, 3-56 

String data types, 4-4 

String with bounds descriptors, 5-29 

Synchronization 
exception, 2-8 
memory, 2-8 

SYS$CALL_HANDL+4 routine 
using, 6—24 

SYS$GOTO_UNWIND routine, 6-26 
unwinding, 6-28 

SYS$UNWIND routine 
unwinding, 6—23, 6-28 


T 


TEBs (thread environment blocks), 3—59 


Thread environment blocks 
See TEBs 

Thread-safe code 
definition, 1-6 

Threads of execution 
definition, 1-6 

Transfer code 
address, 3-44 
sequence, 3-44 
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TRAPB instruction, 6-20 


V 


U Variable buffer descriptors, 5-33 
Unaligned bit array descriptors, 5-25 Variable-size stack frames, 3-10 
Unaligned bit string descriptors, 5-24 Varying character string data types, 4-6 
Unaligned bit string with bounds descriptors, Varying string 
5-31 returned to stack, 2-8 

Unused bits in passed data, 3-50 Varying string array descriptors, 5-21 
Unwinds Varying string descriptors, 5-19 

completion, 6-25, 6-28 VAX language extension, 2-5 

exit, 6-26 VAX scalar 

GOTO, 6-25 See Scalars 

handler invocation, 6—27 VAX vector 

nested, 6-29 See Vector processors 


operations, 6—23 
multiple active, 6—29 
overlapping, 6—30 


See Vector registers 
Vector processors 

exception handling, 6-16 

synchronization, 2-8 
Vector registers 

usage, 2-2 
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